Janitorial tasks - Revision history

Kris: /* Documentation */

2012-01-06T10:05:13Z

Documentation

← Older revision		Revision as of 10:05, 6 January 2012
Line 134:		Line 134:
	=== @brief Command ===		=== @brief Command ===

	* The <tt>@brief</tt> command comes from the more complex documentation format implemented by Trolltech before Doxygen was created. When the <tt>@brief</tt> command is skipped, Doxygen will use the first sentence (ending with a dot) as the brief description. An alternative is to put the description in a single-line comment. These two techniques can be used to reduce the number of Doxygen commands. In the example below, all three functions will have the same documentation. The first case depends on the variable JAVADOC_AUTOBRIEF being set to true, which is a main setting for Inkscape ~~documenation~~:		* The <tt>@brief</tt> command comes from the more complex documentation format implemented by Trolltech before Doxygen was created. When the <tt>@brief</tt> command is skipped, Doxygen will use the first sentence (ending with a dot) as the brief description. An alternative is to put the description in a single-line comment. These two techniques can be used to reduce the number of Doxygen commands. In the example below, all three functions will have the same documentation. The first case depends on the variable JAVADOC_AUTOBRIEF being set to true, which is a main setting for Inkscape documentation:

	/**		/**

JonCruz: /* Documentation */ info on where to document classes

2012-01-06T10:04:08Z

Documentation: info on where to document classes

← Older revision		Revision as of 10:04, 6 January 2012
Line 117:		Line 117:

	== Documentation ==		== Documentation ==

			=== Document At Point of Declaration ===

			* Items should normally be documented at their point of declaration, not definition.
			* For classes, namespaces, etc. this usually means to document in the .h file and not in the .cpp file.
			** The .h file represents the public API, or promise of functionality.
			** Doxygen comments have not been seen to be updated frequently enough to cause compilation issues from the .h files being touched. (Some developers had expressed concern that having comments in .h files would cause more frequent compilations)
			** It is easier for developers to read through a .h file for information on a class than going through an entire .cpp or set of .cpp files. Additionally, most modern development IDEs support ease of browsing, referencing, etc.
			* For local functions , declaring them at the beginning of the file they are local to and then implementing them later in the file allows a developer to quickly skim a summary of supported functionality. Pairing the doc comments with the initial declaration as opposed to the latter implementation helps legibility.
			** Of course, functions local to a single file should no longer be declared <tt>static</tt>, but instead be declared inside an anonymous namespace section in the file.

	=== Make Comments Meaningful ===		=== Make Comments Meaningful ===

JonCruz: Added more detail and broke things up into proper sections and subsections. Will allow for future edits to be more targeted.

2012-01-06T09:40:54Z

Added more detail and broke things up into proper sections and subsections. Will allow for future edits to be more targeted.

Show changes

Tweenk: /* Source formatting */ remove unrelated note, forward declarations != forward declaration headers; rm "see above" which could be misunderstood as "headers only"

2012-01-04T23:20:54Z

Source formatting: remove unrelated note, forward declarations != forward declaration headers; rm "see above" which could be misunderstood as "headers only"

← Older revision		Revision as of 23:20, 4 January 2012
Line 57:		Line 57:
	#include "xml/node.h"		#include "xml/node.h"
	* Order of the file. Each file should contain the following, in '''precisely''' that order:		* Order of the file. Each file should contain the following, in '''precisely''' that order:
	** <tt>@file</tt> comment with a short description of the file's contents.		** <tt>@file</tt> comment with a short description of the file's contents
	** Copyright comment with authors.		** Copyright comment with authors
	** Include guard (headers only)		** Include guard (headers only)
	** System includes		** System includes
	** Local includes		** Local includes
	** Forward declarations (note: although using an explicit forward declaration file used to be recommended, it no longer is. Using one had been found to be inefficient and error-prone. note on this note: lib2geom devs like 2geom/forward.h, so keep using it there! )		** Forward declarations
	** Class declarations		** Class declarations
	** Function declarations		** Function declarations
	** Global variable declarations (note: global variables should be avoided)		** Global variable declarations (note: global variables should be avoided)
	** End of include guard (headers only)		** End of include guard (headers only)
	** Emacs local variables block ~~(see above)~~		** Emacs local variables block
	** Vim modeline ~~(see above)~~		** Vim modeline

	== Documentation ==		== Documentation ==

Tweenk: /* Improving headers for compilation speed */

2012-01-04T23:18:54Z

Improving headers for compilation speed

← Older revision		Revision as of 23:18, 4 January 2012
Line 14:		Line 14:
	};		};

	Although there are still forward declaration headers in the source tree, those should be avoided in favor of individual forward declarations in .h files as needed. '''The exception is <tt>>2geom/forward.h<</tt>''', due to heavy use of templates in the 2Geom library.		Although there are still forward declaration headers in the source tree, those should be avoided in favor of individual forward declarations in .h files as needed. '''The exception is <tt><2geom/forward.h></tt>''', due to heavy use of templates in the 2Geom library.

	(BPF) The [http://www.parashift.com/c++-faq-lite/misc-technical-issues.html#faq-39.11 C++ FAQ Sheet] explains how to code forward declarations (classes that both need to know about each other); To fully understand why, you should study the [http://www.gotw.ca/publications/mill04.htm Pimpl idiom].		(BPF) The [http://www.parashift.com/c++-faq-lite/misc-technical-issues.html#faq-39.11 C++ FAQ Sheet] explains how to code forward declarations (classes that both need to know about each other); To fully understand why, you should study the [http://www.gotw.ca/publications/mill04.htm Pimpl idiom].

Tweenk: /* Improving headers for compilation speed */

2012-01-04T23:18:36Z

Improving headers for compilation speed

← Older revision		Revision as of 23:18, 4 January 2012
Line 14:		Line 14:
	};		};

	Although there are still forward declaration headers in the source tree, those should be avoided in favor of individual forward declarations in .h files as needed.		Although there are still forward declaration headers in the source tree, those should be avoided in favor of individual forward declarations in .h files as needed. '''The exception is <tt>>2geom/forward.h<</tt>''', due to heavy use of templates in the 2Geom library.

	(BPF) The [http://www.parashift.com/c++-faq-lite/misc-technical-issues.html#faq-39.11 C++ FAQ Sheet] explains how to code forward declarations (classes that both need to know about each other); To fully understand why, you should study the [http://www.gotw.ca/publications/mill04.htm Pimpl idiom].		(BPF) The [http://www.parashift.com/c++-faq-lite/misc-technical-issues.html#faq-39.11 C++ FAQ Sheet] explains how to code forward declarations (classes that both need to know about each other); To fully understand why, you should study the [http://www.gotw.ca/publications/mill04.htm Pimpl idiom].

Tweenk: /* Source formatting */

2012-01-04T23:15:06Z

Source formatting

← Older revision		Revision as of 23:15, 4 January 2012
Line 57:		Line 57:
	#include "xml/node.h"		#include "xml/node.h"
	* Order of the file. Each file should contain the following, in '''precisely''' that order:		* Order of the file. Each file should contain the following, in '''precisely''' that order:
	** <tt>@file</tt> comment~~, which marks~~ the file ~~as containing documented entities. You can skip it for files that contain no documentation~~.		** <tt>@file</tt> comment with a short description of the file's contents.
	** Copyright comment~~, as above~~.		** Copyright comment with authors.
	** Include guard (only ~~for header files~~)		** Include guard (headers only)
	** System includes		** System includes
	** Local includes		** Local includes
Line 66:		Line 66:
	** Function declarations		** Function declarations
	** Global variable declarations (note: global variables should be avoided)		** Global variable declarations (note: global variables should be avoided)
	** End of include guard		** End of include guard (headers only)
	** Emacs local variables block (see above)		** Emacs local variables block (see above)
	** Vim modeline (see above)		** Vim modeline (see above)

Tweenk: /* Source formatting */

2012-01-04T23:12:35Z

Source formatting

← Older revision		Revision as of 23:12, 4 January 2012
Line 20:		Line 20:
	== Source formatting ==		== Source formatting ==
	* Source files should use four spaces as indentation and no tabs. Trailing whitespace should be removed.		* Source files should use four spaces as indentation and no tabs. Trailing whitespace should be removed.
	* The comment at the top of each file should have the following format. The author information is in a regular multiline comment. Author emails can be obfuscated, but should be real addresses.		* The comment at the top of each file should have the following format. First comes a Doxygen comment with a short description of the contents of the file. You should avoid meaningless descriptions such as "Inkscape::Preferences class implementation". Instead, if there is one class in the file, describe in a few words what this class is used for. If there are several, describe what they have in common. The author information is in a regular multiline comment so that it is omitted in the generated documentation. Author emails can be obfuscated, but should be real addresses.
			/** @file
	/**
	* @file
	* Logarithmic time travelling salesman solver		* Logarithmic time travelling salesman solver
	//		//

Tweenk: /* Documentation */

2012-01-04T23:06:11Z

Documentation

← Older revision		Revision as of 23:06, 4 January 2012
Line 74:		Line 74:
	== Documentation ==		== Documentation ==

	* Many files begin with a Doxygen comment that doesn't contain the <tt>@file</tt> tag. The result is that the comment doesn't document the file, but the first entity declared in the file, usually the <tt>Inkscape</tt> namespace. ~~File-centric Doxygen comments should normally be avoided, thus these should be moved elsewhere. Thus the~~ file ~~should start a regular comment with the author and copyright information~~.		* Many files begin with a Doxygen comment that doesn't contain the <tt>@file</tt> tag. The result is that the comment doesn't document the file, but the first entity declared in the file, usually the <tt>Inkscape</tt> namespace. Add a <tt>@file</tt> directive to them.
	* Some documentation is useless, for example "constructor" or "destructor". Such comments mark the entity as documented, when in fact it's not. Remove them.		* Some documentation is useless, for example "constructor" or "destructor". Such comments mark the entity as documented, when in fact it's not. Remove them.
			* When the <tt>@brief</tt> tag is skipped, Doxygen will use the first sentence (ending with a dot) as the brief description. An alternative is to put the description in a single-line comment. These two techniques can be used to reduce the number of directives. In the example below, all three functions will have the same documentation. The second case depends on the variable JAVADOC_AUTOBRIEF being set to true:
			/// Something useful
			/** This function does something very useful.
			* Here is its more detailed, longer description. */
			void useful_function_one();

			/** Something useful.
			* This function does something very useful.
			* Here is its more detailed, longer description. */
			void useful_function_two();

			/** @brief Something useful.
			* This function does something very useful.
			* Here is its more detailed, longer description. */
			void useful_function_three();

	== Coding style ==		== Coding style ==

Tweenk: /* Source formatting */ revert Jon's misleading changes about @file

2012-01-04T22:58:44Z

Source formatting: revert Jon's misleading changes about @file

← Older revision		Revision as of 22:58, 4 January 2012
Line 21:		Line 21:
	* Source files should use four spaces as indentation and no tabs. Trailing whitespace should be removed.		* Source files should use four spaces as indentation and no tabs. Trailing whitespace should be removed.
	* The comment at the top of each file should have the following format. The author information is in a regular multiline comment. Author emails can be obfuscated, but should be real addresses.		* The comment at the top of each file should have the following format. The author information is in a regular multiline comment. Author emails can be obfuscated, but should be real addresses.
	** ~~Using a Doxygen comment with <tt>~~@file</tt> at the top should no longer be the normal case. The comments need to document individual classes, subsystems, etc., and not be focused on file structure. Doxygen itself normally will address file-specific needs.
	/*		/**
			* @file
			* Logarithmic time travelling salesman solver
			//
	* Authors:		* Authors:
	* J. God Hacker <ihatepizza@gurus.org>		* J. God Hacker <ihatepizza@gurus.org>
Line 56:		Line 59:
	#include "xml/node.h"		#include "xml/node.h"
	* Order of the file. Each file should contain the following, in '''precisely''' that order:		* Order of the file. Each file should contain the following, in '''precisely''' that order:
			** <tt>@file</tt> comment, which marks the file as containing documented entities. You can skip it for files that contain no documentation.
	** Copyright comment, as above.		** Copyright comment, as above.
	** Include guard (only for header files)		** Include guard (only for header files)