Platform/GFX/DesignDocumentationGuidelines

Why

What

Documenting design for the upcoming work

We will start the conversation about the design in a bug. Design work in progress can be attached to the bug, we can record feedback, reviews, etc. It is expected that we will keep those documents in the same format as what will eventually be landed to gfx/doc directory.

Once the design is mature enough, even if not complete, it should be landed in the gfx/doc directory. We want to make sure that the design in progress is differentiated from the final design, or that which already has implementation behind it. The recommended approach is to create an empty level 2 header that describes that state of the document. This should immediately follow the first level 1 header in the document.

Documenting design for the historical work

In this case, we're trying to retroactively document the design of something that already exists. As soon as something useful exists, we should land it, even if it does not completely document the design. This is especially the case if multiple people are going to be needed in order to document the whole piece of work. Like above, make sure the first level 2 header is explaining the fact that this is work in progress.

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/doc 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)
• Use === for the first top level header and give it a label (all lower case.) This label will be used for referencing from elsewhere.
• 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:
  • @ref pagelabel
  • [this way](@ref pagelabel)
• Good because:
  • The documentation is versioned
  • The documentation is subject to reviews
• For example: Create MyExampleDesign.md that starts with:

My Example Design {#myexampledesign}

Some awesome design description and details ...

Elsewhere, you would use @ref myexampledesign to reference this external design doc.

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?

Using ====== for level 1 headers instead of # seems to play better with Doxygen when using the labels:

This is header level 1 {#nameofthefileinlowercase}
======================

rather than

1. This is header level 1 {#nameofthefileinlowercase}

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.