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
  • 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 designs documented as external files (see section below.)
• 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 .md extension (assuming it is markdown)
• Use the markdown syntax (and if not, make sure you understand why not)
• Put the text between quotes (but not including them) "\page pagenameinlowercase Page Title Text" as the first line in your .md file
• The source file could/should contain a pointer to the documentation, and vice versa.
• The documentation file may reference classes or files themselves:
  • mozilla::gfx::SomeClass
  • @ref mozilla::gfx::SomeClass
  • [link text](@ref mozilla::gfx::SomeClass)
  • SomeClassFile.h
• The source (or other external files) may reference the documentation file:
  • [this way](@ref pagenameinlowercase)
• 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.