Platform/GFX/DesignDocumentationGuidelines: Difference between revisions

From MozillaWiki
< Platform‎ | GFX
Jump to navigation Jump to search
Line 12: Line 12:


* Document the design for class Foo in Foo.h
* Document the design for class Foo in Foo.h
* The documentation is where the source is
* Use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html here] for details
* The documentation is versioned
* This is good because:
* The documentation is subject to reviews
** The documentation is where the source is
* You would use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html this]
** The documentation is versioned
** The documentation is subject to reviews


=== In a separate file in the gfx/docs directory ===
=== In a separate file in the gfx/docs directory ===

Revision as of 20:05, 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
  • This is 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 the markdown syntax
  • The documentation is versioned
  • The documentation is subject to reviews
  • The source file should contain a pointer to the documentation, and vice versa. Use the markdown syntax.
  • There is no preference between this and the 'in source code' approach. Use what's more appropriate, except do not have documentation for the same design in both source and separate file.

In wiki, blog, random web page, etc.

  • Sometimes this is necessary, but don't overuse it
  • The source file should contain a pointer to the documentation, and vice versa. Use the doxygen syntax.