Confirmed users
564
edits
Platform/GFX/DesignDocumentationGuidelines: Difference between revisions
Platform/GFX/DesignDocumentationGuidelines (view source)
Revision as of 21:11, 11 April 2014
, 11 April 2014no edit summary
Msreckovic (talk | contribs) |
Msreckovic (talk | contribs) No edit summary |
||
| Line 13: | Line 13: | ||
* Document the design for class Foo in Foo.h | * Document the design for class Foo in Foo.h | ||
* Use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html here] for details | * Use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html here] for details | ||
** For classes, you need to specify the namespace if it's different from the current class, at least to account for the differences in nested namespaces. (So, Skia referencing SurfaceStream has to use mozilla::gfx::SurfaceStream, but DrawBuffer referencing SurfaceStream can just use gfx::SurfaceStream.) | |||
** You can reference external files using their name. | |||
* Good because: | * Good because: | ||
** The documentation is where the source is | ** The documentation is where the source is | ||
| Line 23: | Line 25: | ||
* Use the markdown syntax (and if not, why not?) | * Use the markdown syntax (and if not, why not?) | ||
* The source file should contain a pointer to the documentation, and vice versa. | * The source file should contain a pointer to the documentation, and vice versa. | ||
* The documentation file may reference classes: | * The documentation file may reference classes or files themselves: | ||
** @ref mozilla::gfx::SomeClass | ** mozilla::gfx::SomeClass | ||
** @ref mozilla::gfx::SomeClass | |||
** [link text](@ref mozilla::gfx::SomeClass) | |||
** SomeClassFile.h | |||
* The source may reference the documentation file: | * The source may reference the documentation file: | ||
** | ** | ||