Policies/Library Documentation Policy - Revision history

Neverendingo: Text replace - "" to ""

2011-06-29T20:57:28Z

Text replace - "</code>" to "</syntaxhighlight>"

Neverendingo: Text replace - "`" to ""`


2011-06-29T20:31:30Z
Text replace - "<code cppqt>" to "<syntaxhighlight lang="cpp-qt">"

				
				
				
				
			
			← Older revision
			Revision as of 20:31, 29 June 2011
			
Line 74:
Line 74:
    
  If Doxygen complains about a particular parameter not being documented, document it. A typical example is:   If Doxygen complains about a particular parameter not being documented, document it. A typical example is:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /**   /**
    * @param msecs the number of milliseconds until the timeout     * @param msecs the number of milliseconds until the timeout
Line 83:
Line 83:
  Here the second parameter is not documented, and Doxygen will complain. Add the relevant documentation — otherwise crucial information about the use of the class is missing.   Here the second parameter is not documented, and Doxygen will complain. Add the relevant documentation — otherwise crucial information about the use of the class is missing.
  If Doxygen complains about <tt>@param</tt> referring to a parameter that isn't there, add the name for the parameter.   If Doxygen complains about <tt>@param</tt> referring to a parameter that isn't there, add the name for the parameter.
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /**   /**
    * @param msecs the number of milliseconds until the timeout     * @param msecs the number of milliseconds until the timeout
Line 96:
Line 96:
  Sometimes there's a conflict between reducing Doxygen warnings and compile warnings. This happens in interface definitions where you give a default implementation of a method with no real body, like the following:   Sometimes there's a conflict between reducing Doxygen warnings and compile warnings. This happens in interface definitions where you give a default implementation of a method with no real body, like the following:
    
− <code cppqt>virtual void setTimeout(uint, bool) { }</code> + <syntaxhighlight lang="cpp-qt">virtual void setTimeout(uint, bool) { }</code>
    
  This compiles fine; Doxygen will complain about missing names, so you add names:   This compiles fine; Doxygen will complain about missing names, so you add names:
    
− <code cppqt>virtual void setTimeout(uint timeout, bool repeat) { }</code> + <syntaxhighlight lang="cpp-qt">virtual void setTimeout(uint timeout, bool repeat) { }</code>
    
  Now the compilation gives warnings because parameters timeout and repeat are not used in the function body. There is the <tt>[http://doc.trolltech.com/4.2/qtglobal.html#Q_UNUSED Q_UNUSED]</tt> macro to deal with this. It "uses" its argument, which shuts the compiler up.   Now the compilation gives warnings because parameters timeout and repeat are not used in the function body. There is the <tt>[http://doc.trolltech.com/4.2/qtglobal.html#Q_UNUSED Q_UNUSED]</tt> macro to deal with this. It "uses" its argument, which shuts the compiler up.
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
    virtual void setTimeout(uint timeout, bool repeat)     virtual void setTimeout(uint timeout, bool repeat)
    { Q_UNUSED(timeout); Q_UNUSED(repeat); }     { Q_UNUSED(timeout); Q_UNUSED(repeat); }



Neverendingo: Fix a typo
2010-04-29T12:33:25Z
Fix a typo

				
				
				
				
			
			← Older revision
			Revision as of 12:33, 29 April 2010
			
Line 67:
Line 67:
  == Check the Spelling and Grammar ==   == Check the Spelling and Grammar ==
    
− Documentation represents a project a lot more then you might think. Take the time to give it the proper polish it deserves. For a lot of developers the documentation will not only explain what the class does, but will be the only view into how the class works. + Documentation represents a project a lot more than you might think. Take the time to give it the proper polish it deserves. For a lot of developers the documentation will not only explain what the class does, but will be the only view into how the class works.
    
  == Build the API Documentation before Committing any Code ==   == Build the API Documentation before Committing any Code ==



Dhaumann: link how to create the API documentation correctly. Hope that works.
2008-12-10T09:00:56Z
link how to create the API documentation correctly. Hope that works.

				
				
				
				
			
			← Older revision
			Revision as of 09:00, 10 December 2008
			
Line 69:
Line 69:
  Documentation represents a project a lot more then you might think. Take the time to give it the proper polish it deserves. For a lot of developers the documentation will not only explain what the class does, but will be the only view into how the class works.   Documentation represents a project a lot more then you might think. Take the time to give it the proper polish it deserves. For a lot of developers the documentation will not only explain what the class does, but will be the only view into how the class works.
    
− == Run "make apidox" before Committing any Code == + == Build the API Documentation before Committing any Code ==
    
− Fix any errors and or warning in the documention so others don't have to. + [[Development/Tools/apidox|Fix any errors and or warning]] in the documention so others don't have to.
    
  If Doxygen complains about a particular parameter not being documented, document it. A typical example is:   If Doxygen complains about a particular parameter not being documented, document it. A typical example is:



Dhaumann: , code -> tt

2006-12-21T18:07:30Z
<code cppqt>, code -> tt

				
				
				
				
			
			← Older revision
			Revision as of 18:07, 21 December 2006
			
Line 7:
Line 7:
  Doxygen uses the first sentence of the class to generate a short class description. This sentence should provide the reason for why the class exists and when to use it, i.e. the description should give an simple overview of what the class does. Examples: "KMyWidgetClass is a class to handle lists", "A widget that shows balls bouncing.", "Monitors directory(s) for changes". The first sentence should be able to stand on its own when displayed by an IDE as the short discription. Suggestions for when the class should and '''should not''' be used are very helpful, same with referencing classes that are similar, but fill different needs.   Doxygen uses the first sentence of the class to generate a short class description. This sentence should provide the reason for why the class exists and when to use it, i.e. the description should give an simple overview of what the class does. Examples: "KMyWidgetClass is a class to handle lists", "A widget that shows balls bouncing.", "Monitors directory(s) for changes". The first sentence should be able to stand on its own when displayed by an IDE as the short discription. Suggestions for when the class should and '''should not''' be used are very helpful, same with referencing classes that are similar, but fill different needs.
    
− <code>@author</code> should be used to show who the author(s) of the class are. If there are more then one <code>@author</code> tags, <code>\par Maintainer: Foo Bar (foo@bar.com)</code> should be added. This is required so that developers will know whom is the correct person to contact when they find a bug or have a patch. + <tt>@author</tt> should be used to show who the author(s) of the class are. If there are more then one <tt>@author</tt> tags, <tt>\par Maintainer: Foo Bar (foo@bar.com)</tt> should be added. This is required so that developers will know whom is the correct person to contact when they find a bug or have a patch.
    
  == Provide Example Code ==   == Provide Example Code ==
    
− A simple example usage of the class should be provided. Not only does example code show how the functions in the class interact, but they are good summaries and should be placed in the class descriptions. Note that developers will often copy this coder verbatim as a starting point and so great care should be taken to make sure that the code is clean, clear and concise. Good full variable names such as ''stream'' or ''file'' should be chosen instead of abbreviations like ''s'' and ''fl''. <code>@code</code> and <code>@endcode</code> should be used to mark code examples. + A simple example usage of the class should be provided. Not only does example code show how the functions in the class interact, but they are good summaries and should be placed in the class descriptions. Note that developers will often copy this coder verbatim as a starting point and so great care should be taken to make sure that the code is clean, clear and concise. Good full variable names such as ''stream'' or ''file'' should be chosen instead of abbreviations like ''s'' and ''fl''. <tt>@code</tt> and <tt>@endcode</tt> should be used to mark code examples.
    
  == Example Application ==   == Example Application ==
Line 38:
Line 38:
    @since     @since
    
− <code>@param</code>, <code>@return</code> etc should be in all lower case. If there is just once sentence then there should be no period at the end. The first word should not be capitalized and there should not be a dash between the parameter name and the description. The "-" is added by the doc processor and if the developer adds one then there might be two in the resulting html/pdf/tex/etc documentation. + <tt>@param</tt>, <tt>@return</tt> etc should be in all lower case. If there is just once sentence then there should be no period at the end. The first word should not be capitalized and there should not be a dash between the parameter name and the description. The "-" is added by the doc processor and if the developer adds one then there might be two in the resulting html/pdf/tex/etc documentation.
    
  ; Correct   ; Correct
Line 48:
Line 48:
    @param foo'''-'''the value to convert     @param foo'''-'''the value to convert
    
− Functions that return bool should not use "iff" in <code>@return</code> statements: + Functions that return bool should not use "iff" in <tt>@return</tt> statements:
    
  ; Correct   ; Correct
Line 55:
Line 55:
    @return @c true '''iff''' button is on and is a toggle button     @return @c true '''iff''' button is on and is a toggle button
    
− <code>@deprecated</code> should be added to any function or class that should be removed in the next binary incompatible release (3.0, 4.0, 5.0). They should also state the class/function that replaces it. + <tt>@deprecated</tt> should be added to any function or class that should be removed in the next binary incompatible release (3.0, 4.0, 5.0). They should also state the class/function that replaces it.
    
  == Document Enumerations ==   == Document Enumerations ==
Line 74:
Line 74:
    
  If Doxygen complains about a particular parameter not being documented, document it. A typical example is:   If Doxygen complains about a particular parameter not being documented, document it. A typical example is:
−  /** + <code cppqt>
−   * @param msecs the number of milliseconds until the timeout + /**
−   *        is signalled +  * @param msecs the number of milliseconds until the timeout
−   */ +  *        is signalled
−  void setTimeout(uint msecs, bool repeat) +  */
−   + void setTimeout(uint msecs, bool repeat)
  + </code>
  Here the second parameter is not documented, and Doxygen will complain. Add the relevant documentation — otherwise crucial information about the use of the class is missing.   Here the second parameter is not documented, and Doxygen will complain. Add the relevant documentation — otherwise crucial information about the use of the class is missing.
− If Doxygen complains about <code>@param</code> referring to a parameter that isn't there, add the name for the parameter. + If Doxygen complains about <tt>@param</tt> referring to a parameter that isn't there, add the name for the parameter.
−   + <code cppqt>
−  /** + /**
−   * @param msecs the number of milliseconds until the timeout +  * @param msecs the number of milliseconds until the timeout
−   *        is signalled +  *        is signalled
−   * @param repeat whether the timeout should happen every +  * @param repeat whether the timeout should happen every
−   *        @p msecs milliseconds, or just once +  *        @p msecs milliseconds, or just once
−   */ +  */
−  void setTimeout(uint, bool) + void setTimeout(uint, bool)
−   + </code>
  Here, Doxygen will complain that the names of the parameters do not occur in the function signature. Add the names. The lack of names can be really confusing if you have a method with several parameters of the same type. Probably the documentation lists the parameters in the order they occur in the function signature, but there's no way to tell. ''Use names''.   Here, Doxygen will complain that the names of the parameters do not occur in the function signature. Add the names. The lack of names can be really confusing if you have a method with several parameters of the same type. Probably the documentation lists the parameters in the order they occur in the function signature, but there's no way to tell. ''Use names''.
    
  Sometimes there's a conflict between reducing Doxygen warnings and compile warnings. This happens in interface definitions where you give a default implementation of a method with no real body, like the following:   Sometimes there's a conflict between reducing Doxygen warnings and compile warnings. This happens in interface definitions where you give a default implementation of a method with no real body, like the following:
    
−  virtual void setTimeout(uint, bool) { } + <code cppqt>virtual void setTimeout(uint, bool) { }</code>
    
  This compiles fine; Doxygen will complain about missing names, so you add names:   This compiles fine; Doxygen will complain about missing names, so you add names:
    
−  virtual void setTimeout(uint timeout, bool repeat) { } + <code cppqt>virtual void setTimeout(uint timeout, bool repeat) { }</code>
−   + 
− Now the compilation gives warnings because parameters timeout and repeat are not used in the function body. There is the <code>[http://doc.trolltech.com/4.2/qtglobal.html#Q_UNUSED Q_UNUSED]</code> macro to deal with this. It "uses" its argument, which shuts the compiler up. + 
    
  + Now the compilation gives warnings because parameters timeout and repeat are not used in the function body. There is the <tt>[http://doc.trolltech.com/4.2/qtglobal.html#Q_UNUSED Q_UNUSED]</tt> macro to deal with this. It "uses" its argument, which shuts the compiler up.
  + <code cppqt>
    virtual void setTimeout(uint timeout, bool repeat)     virtual void setTimeout(uint timeout, bool repeat)
    { Q_UNUSED(timeout); Q_UNUSED(repeat); }     { Q_UNUSED(timeout); Q_UNUSED(repeat); }
−   + </code>
− With the function defined like this, both Doxygen and the C++ compiler are happy. <code>Q_UNUSED</code> does not incur any run-time penalty. + With the function defined like this, both Doxygen and the C++ compiler are happy. <tt>Q_UNUSED</tt> does not incur any run-time penalty.
    
  [[Category:Policies]]   [[Category:Policies]]



Cullmann: Protected "Policies/Library Documentation Policy" [edit=sysop:move=sysop]
2006-09-28T17:47:39Z
Protected "Policies/Library Documentation Policy" [edit=sysop:move=sysop]

			
			← Older revision
			Revision as of 17:47, 28 September 2006
			


Dhaumann: use path template for paths and filenames.
2006-09-22T18:57:44Z
use path template for paths and filenames.

				
				
				
				
			
			← Older revision
			Revision as of 18:57, 22 September 2006
			
Line 19:
Line 19:
  == Add Screenshots ==   == Add Screenshots ==
    
− If the class is a widget add a screenshot. Screenshots provide a simple and easy way for developers to recognize what the class provides. The screenshots should reside in class description. Images can be placed in <code>kdelibs/doc/api/</code> and included by using + If the class is a widget add a screenshot. Screenshots provide a simple and easy way for developers to recognize what the class provides. The screenshots should reside in class description. Images can be placed in {{path|kdelibs/doc/api/}} and included by using
    \image html myclass.png "Image subtitle"     \image html myclass.png "Image subtitle"
    
  == Qt Designer Integration ==   == Qt Designer Integration ==
    
− If the class exists in [http://doc.trolltech.com/4.2/designer-creating-custom-widgets.html Qt Designer], put a 22x20 image in <code>kdelibs/kdewidgets/pics/</code>. It should look similar to the other KDE button images and provide an easy to understand relationship to the class it represents. + If the class exists in [http://doc.trolltech.com/4.2/designer-creating-custom-widgets.html Qt Designer], put a 22x20 image in {{path|kdelibs/kdewidgets/pics/}}. It should look similar to the other KDE button images and provide an easy to understand relationship to the class it represents.
    
  == Document Public and Protected Members ==   == Document Public and Protected Members ==



Dhaumann: add to category 'Policies'
2006-09-15T11:31:20Z
add to category 'Policies'

				
				
				
				
			
			← Older revision
			Revision as of 11:31, 15 September 2006
			
Line 107:
Line 107:
    
  With the function defined like this, both Doxygen and the C++ compiler are happy. <code>Q_UNUSED</code> does not incur any run-time penalty.   With the function defined like this, both Doxygen and the C++ compiler are happy. <code>Q_UNUSED</code> does not incur any run-time penalty.
  + 
  + [[Category:Policies]]



Dhaumann: typo
2006-09-10T09:35:24Z
typo

				
				
				
				
			
			← Older revision
			Revision as of 09:35, 10 September 2006
			
Line 36:
Line 36:
    @see     @see
    @author     @author
−   @since. +   @since
    
  <code>@param</code>, <code>@return</code> etc should be in all lower case. If there is just once sentence then there should be no period at the end. The first word should not be capitalized and there should not be a dash between the parameter name and the description. The "-" is added by the doc processor and if the developer adds one then there might be two in the resulting html/pdf/tex/etc documentation.   <code>@param</code>, <code>@return</code> etc should be in all lower case. If there is just once sentence then there should be no period at the end. The first word should not be capitalized and there should not be a dash between the parameter name and the description. The "-" is added by the doc processor and if the developer adds one then there might be two in the resulting html/pdf/tex/etc documentation.



Dhaumann: /* Run "make apidox" before Committing any Code */
2006-09-10T09:33:24Z
‎Run "make apidox" before Committing any Code

				
				
				
				
			
			← Older revision
			Revision as of 09:33, 10 September 2006
			
Line 101:
Line 101:
    virtual void setTimeout(uint timeout, bool repeat) { }     virtual void setTimeout(uint timeout, bool repeat) { }
    
− Now the compilation gives warnings because parameters timeout and repeat are not used in the function body. There is the <code>Q_UNUSED</code> macro to deal with this. It "uses" its argument, which shuts the compiler up. + Now the compilation gives warnings because parameters timeout and repeat are not used in the function body. There is the <code>[http://doc.trolltech.com/4.2/qtglobal.html#Q_UNUSED Q_UNUSED]</code> macro to deal with this. It "uses" its argument, which shuts the compiler up.
    
    virtual void setTimeout(uint timeout, bool repeat)     virtual void setTimeout(uint timeout, bool repeat)

← Older revision		Revision as of 11:31, 15 September 2006
Line 107:		Line 107:

	With the function defined like this, both Doxygen and the C++ compiler are happy. <code>Q_UNUSED</code> does not incur any run-time penalty.		With the function defined like this, both Doxygen and the C++ compiler are happy. <code>Q_UNUSED</code> does not incur any run-time penalty.
		+
		+	[[Category:Policies]]