Platform/GFX/DesignDocumentationGuidelines - Revision history

Kats: /* In a separate file in the gfx/docs directory */ s/docs/doc/ because that's what's in m-c

2014-05-13T15:06:27Z

In a separate file in the gfx/docs directory: s/docs/doc/ because that's what's in m-c

← Older revision		Revision as of 15:06, 13 May 2014
Line 30:		Line 30:
	** The documentation is subject to reviews		** The documentation is subject to reviews

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

	* Name the documentation file appropriately, use the .md extension (assuming it is markdown)		* Name the documentation file appropriately, use the .md extension (assuming it is markdown)

Msreckovic at 16:53, 16 April 2014

2014-04-16T16:53:15Z

← Older revision		Revision as of 16:53, 16 April 2014
Line 2:		Line 2:

	== What ==		== 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 ==		== How ==

Msreckovic: /* What kind of a bike shed would you like? */

2014-04-16T15:22:41Z

What kind of a bike shed would you like?

← Older revision		Revision as of 15:22, 16 April 2014
Line 53:		Line 53:

	=== What kind of a bike shed would you like? ===		=== 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:
	~~I personally prefer using~~ ====== for level 1 ~~and ------- for level two~~ headers ~~over # and #~~#:		This is header level 1 {#nameofthefileinlowercase}
	This is header level 1
	======================		======================
	~~This is header level 2~~		rather than
	~~----------------------~~		# This is header level 1 {#nameofthefileinlowercase}
	~~Rather~~ than
	# This is header level 1
	#~~# This is header level 2~~
	~~but that's just a random preference.~~

	== Results ==		== 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.		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.

Msreckovic: /* In a separate file in the gfx/docs directory */

2014-04-14T21:58:59Z

In a separate file in the gfx/docs directory

← Older revision		Revision as of 21:58, 14 April 2014
Line 24:		Line 24:
	* Name the documentation file appropriately, use the .md extension (assuming it is markdown)		* 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 the markdown syntax (and if not, make sure you understand why not)
	* Use === for the first top level header and give it a label. This label will be used for referencing from elsewhere.		* 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 source file could/should contain a pointer to the documentation, and vice versa.
	* The documentation file may reference classes or files themselves:		* The documentation file may reference classes or files themselves:
Line 37:		Line 37:
	** The documentation is versioned		** The documentation is versioned
	** The documentation is subject to reviews		** The documentation is subject to reviews
			* For example: Create MyExampleDesign.md that starts with:
			<code>
			My Example Design {#myexampledesign}
			==================
			Some awesome design description and details
			...
			</code>

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

	=== In wiki, blog, random web page, etc. ===		=== In wiki, blog, random web page, etc. ===

Msreckovic: /* In a separate file in the gfx/docs directory */

2014-04-14T20:13:25Z

In a separate file in the gfx/docs directory

← Older revision		Revision as of 20:13, 14 April 2014
Line 24:		Line 24:
	* Name the documentation file appropriately, use the .md extension (assuming it is markdown)		* 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 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~~		* Use === for the first top level header and give it a label. This label will be used for referencing from elsewhere.
	* The source file could/should contain a pointer to the documentation, and vice versa.		* The source file could/should contain a pointer to the documentation, and vice versa.
	* The documentation file may reference classes or files themselves:		* The documentation file may reference classes or files themselves:
Line 32:		Line 32:
	** SomeClassFile.h		** SomeClassFile.h
	* The source (or other external files) may reference the documentation file:		* The source (or other external files) may reference the documentation file:
	** @ref ~~pagenameinlowercase~~		** @ref pagelabel
	** [this way](@ref ~~pagenameinlowercase~~)		** [this way](@ref pagelabel)
	* Good because:		* Good because:
	** The documentation is versioned		** The documentation is versioned

Msreckovic: /* In a separate file in the gfx/docs directory */

2014-04-14T19:54:47Z

In a separate file in the gfx/docs directory

← Older revision		Revision as of 19:54, 14 April 2014
Line 32:		Line 32:
	** SomeClassFile.h		** SomeClassFile.h
	* The source (or other external files) may reference the documentation file:		* The source (or other external files) may reference the documentation file:
			** @ref pagenameinlowercase
	** [this way](@ref pagenameinlowercase)		** [this way](@ref pagenameinlowercase)
	* Good because:		* Good because:

Msreckovic: /* In a separate file in the gfx/docs directory */

2014-04-14T19:54:00Z

In a separate file in the gfx/docs directory

← Older revision		Revision as of 19:54, 14 April 2014
Line 22:		Line 22:
	=== In a separate file in the gfx/docs directory ===		=== In a separate file in the gfx/docs directory ===

	* Name the documentation file appropriately, use the .md extension (assuming it is markdown~~, and if not, why not?~~)		* 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 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 source file could/should contain a pointer to the documentation, and vice versa.
	* The documentation file may reference classes or files themselves:		* The documentation file may reference classes or files themselves:
Line 31:		Line 32:
	** SomeClassFile.h		** SomeClassFile.h
	* The source (or other external files) may reference the documentation file:		* The source (or other external files) may reference the documentation file:
	** [this way](@ref ~~SomeExternalFile.md~~)		** [this way](@ref pagenameinlowercase)
	** just by name as SomeExternalFile.md
	* Good because:		* Good because:
	** The documentation is versioned		** The documentation is versioned

Msreckovic: /* In a separate file in the gfx/docs directory */

2014-04-14T19:20:16Z

In a separate file in the gfx/docs directory

← Older revision		Revision as of 19:20, 14 April 2014
Line 23:		Line 23:

	* Name the documentation file appropriately, use the .md extension (assuming it is markdown, and if not, why not?)		* Name the documentation file appropriately, use the .md extension (assuming it is markdown, and if not, why not?)
	* Use the markdown syntax (and if not, why not?)		* Use the markdown syntax (and if not, make sure you understand why not)
	* Put \page alllowercasenameofthefile at the top		* The source file could/should contain a pointer to the documentation, and vice versa.
	* The source file should contain a pointer to the documentation, and vice versa.
	* The documentation file may reference classes or files themselves:		* The documentation file may reference classes or files themselves:
	** mozilla::gfx::SomeClass		** mozilla::gfx::SomeClass
Line 32:		Line 31:
	** SomeClassFile.h		** SomeClassFile.h
	* The source (or other external files) may reference the documentation file:		* The source (or other external files) may reference the documentation file:
	** [this way](@ref ~~alllowercasenameofthefile~~)		** [this way](@ref SomeExternalFile.md)
			** just by name as SomeExternalFile.md
	* Good because:		* Good because:
	** The documentation is versioned		** The documentation is versioned

Msreckovic: /* In the source code */

2014-04-14T19:18:53Z

In the source code

← Older revision		Revision as of 19:18, 14 April 2014
Line 14:		Line 14:
	* Use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html here] for details		* Use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html 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.)		** 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 external files (see section below.)		** You can reference designs documented as external files (see section below.)
	* Good because:		* Good because:
	** The documentation is where the source is		** The documentation is where the source is

Msreckovic: /* In the source code */

2014-04-11T21:52:41Z

In the source code

← Older revision		Revision as of 21:52, 11 April 2014
Line 14:		Line 14:
	* Use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html here] for details		* Use doxygen+markdown syntax; see [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html 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.)		** 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 external files ~~using their name~~.		** You can reference external files (see section below.)
	* Good because:		* Good because:
	** The documentation is where the source is		** The documentation is where the source is