diff --git a/platform/DirHandle.h b/platform/DirHandle.h
index d0b04d04f2..d40300e360 100644
--- a/platform/DirHandle.h
+++ b/platform/DirHandle.h
@@ -30,18 +30,24 @@ namespace mbed {
  */
 
 
-/** Represents a directory stream. Objects of this type are returned
- *  by an opendir function. The core functions are read and seek,
+/** Represents a directory stream. An opendir function returns 
+ *  objects of this type. The core functions are read and seek,
  *  but only a subset needs to be provided.
  *
- *  If a FileSystemLike class defines the opendir method, then the
- *  directories of an object of that type can be accessed by
- *  DIR *d = opendir("/example/directory") (or opendir("/example")
- *  to open the root of the filesystem), and then using readdir(d) etc.
+ *  If a FileSystemLike class defines the opendir method, then you
+ *  can access the directories of an object of that type by either:
+ *  @code
+ *  DIR *d  = opendir("/example/directory");
+ *  @endcode
+ *  or
+ *  @code
+ *  DIR *d = opendir("/example");
+ *  @endcode
+ *  to open the root of the file system.
  *
  *  The root directory is considered to contain all FileHandle and
- *  FileSystem objects, so the DIR* returned by opendir("/") will
- *  reflect this.
+ *  FileSystem objects, so the DIR pointer returned by opendir("/")
+ *  reflects this.
  *
  *  @note to create a directory, @see Dir
  *  @note Synchronization level: Set by subclass
@@ -113,7 +119,7 @@ public:
         return close();
     };
 
-    /** Return the directory entry at the current position, and
+    /** Returns the directory entry at the current position, and
      *  advances the position to the next entry.
      *
      * @returns