Platform/GFX/DesignDocumentationGuidelines: Difference between revisions
Jump to navigation
Jump to search
Msreckovic (talk | contribs) |
Msreckovic (talk | contribs) (→How) |
||
| 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 | ||
* | * Good because: | ||
** The documentation is where the source is | ** The documentation is where the source is | ||
** The documentation is versioned | ** The documentation is versioned | ||
| Line 20: | Line 20: | ||
=== In a separate file in the gfx/docs directory === | === In a separate file in the gfx/docs directory === | ||
* Name the documentation file appropriately | * Name the documentation file appropriately, use .text extension | ||
* Use the markdown syntax | * Use the markdown syntax | ||
* The source file should contain a pointer to the documentation, and vice versa. Use the markdown syntax. | * The source file should contain a pointer to the documentation, and vice versa. Use the markdown syntax. | ||
* | * Good because: | ||
** The documentation is versioned | |||
** The documentation is subject to reviews | |||
=== In wiki, blog, random web page, etc. === | === In wiki, blog, random web page, etc. === | ||
* Sometimes this is necessary, but don't overuse it | * Sometimes this is necessary, but don't overuse it. Good usage scenarios are blog posts, and such. | ||
* 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. | ||
== Results == | |||
If we follow the above rules, everything should nicely get extracted to html, for those browsing graphics documentation pages, while also providing in source information for those browsing the source. | |||
Revision as of 20:10, 10 April 2014
Why
What
How
We want the design documentation is as close to the source that implements it as possible. We also anticipate having the design evolve, and in particular, at times having the design (as the implementation) differ between different trains. For example, mozilla-central may contain the updated design and implementation for a feature, while the mozilla-aurora still contains the previous version.
Recommended options are:
In the source code
- Document the design for class Foo in Foo.h
- Use doxygen+markdown syntax; see here for details
- Good because:
- The documentation is where the source is
- The documentation is versioned
- The documentation is subject to reviews
In a separate file in the gfx/docs directory
- Name the documentation file appropriately, use .text extension
- Use the markdown syntax
- The source file should contain a pointer to the documentation, and vice versa. Use the markdown syntax.
- Good because:
- The documentation is versioned
- The documentation is subject to reviews
In wiki, blog, random web page, etc.
- Sometimes this is necessary, but don't overuse it. Good usage scenarios are blog posts, and such.
- The source file should contain a pointer to the documentation, and vice versa.
Results
If we follow the above rules, everything should nicely get extracted to html, for those browsing graphics documentation pages, while also providing in source information for those browsing the source.