Platform/GFX/DesignDocumentationGuidelines

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
• The documentation is where the source is
• The documentation is versioned
• The documentation is subject to reviews
• You would use doxygen+markdown syntax; see this

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 doxygen 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.