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
• 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 the markdown syntax and .md extension for the file (unless you have a really good reason not to)
• 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.

What kind of a bike shed would you like?

I personally prefer using ====== for level 1 and ------- for level two headers over # and ##:

This is header level 1
======================
This is header level 2
----------------------

Rather than

# This is header level 1
## This is header level 2

but that's just a random preference.

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.