Difference between revisions of "Policies/KDE4 Library Documentation Policy"

Jump to: navigation, search
m (markup)
m (Text replace - "</code>" to "</syntaxhighlight>")
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
A class exists in the KDE libraries because it wants to be used by many KDE applications. To help in that endeavor it should be fully documented to let any developer use it. New classes that are added to kdelibs must comply with this doc, all existing classes are grandfathered in, but need to be updated to comply if they do not. The KDE library documention is based upon the [http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide Java documentation specification]. Follow the link for full in depth documentation about that format.
+
Classes in the KDE libraries are used by many KDE applications, hence, their usage should be as simple as possible. To help in that endeavor it should be fully documented to let any developer use it. New classes that are added to kdelibs must comply with this doc, all existing classes are grandfathered in, but need to be updated to comply if they do not. The KDE library documention is based upon the [http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide Java documentation specification]. Follow the link for full in depth documentation about that format.
  
These guidelines apply not only to classes in kdelibs, but also to libraries elsewhere (KDE PIM, for instance, has a large number of support libraries that need documentation). To some extent they also apply to applications, if only so that it is easier for outside developers to contribute meaningfully to the application --- well-documented code is easy-to-extend code.
+
These guidelines apply not only to classes in kdelibs, but also to libraries elsewhere (KDE PIM, for instance, has a large number of support libraries that need documentation). To some extent they also apply to applications, if only so that it is easier for new developers to contribute meaningfully to the application well-documented code is easy-to-extend code.
  
=== Class descriptions should provide the reason for the class's existence and when to use it ===
+
== Add a Class Description ==
  
The first sentence of 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.
  
=== Example usage in the class description ===
+
== Provide Example Code ==
  
A simple example usage of the class should be provided. Not only does example usage 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 vs "s" and "fl". @code and /@endcode 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.
  
=== If applicable an example application which shows usage of the class ===
+
== Example Application ==
  
A test application or existing application that a developer can reference is an excellent resource for developers looking to learn about the class. This shouldn't be hard because for any class to be in kdelibs it should already exists in two KDE applications.
+
If applicable, provide an example application which shows the usage of the class. A test application or existing application that a developer can reference is an excellent resource for developers looking to learn about the class. This shouldn't be hard because for any class to be in kdelibs it should already exists in two KDE applications.
  
=== If the class is a widget have screenshot(s) showing example usage ===
+
== Add Screenshots ==
  
Screenshots provide a simple and easy way for developers to recognize what the class provides. The screenshots should reside in class description. Image can be placed in "kdelibs/doc/api/".
+
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"
  
=== If the class exists in Qt Designer an image should exist ===
+
== Qt Designer Integration ==
  
The 22x20 image should be placed in "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.
+
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.
  
=== All public and protected functions must have documentation ===
+
== Document Public and Protected Members ==
  
Developers do not read reference documentation like a book, they scan it for the information that they need. This is why it is important that everything is at the place they expect it to be. IDE's might parse the functions and so it is important that the correct meta data is present and not hidden in the description. Function should use the "@" tags in the following order: <code>@brief</code>, <code>@description</code>, <code>@param</code>, <code>@return</code>, <code>@exception</code>, <code>@see</code>, <code>@author</code>, <code>@since</code>.
+
Developers do not read reference documentation like a book, they scan it for the information that they need. This is why it is important that everything is at the place they expect it to be. IDE's might parse the functions and so it is important that the correct meta data is present and not hidden in the description. Function should use the "@" tags in the following order:
 +
@brief
 +
@description
 +
@param
 +
@return
 +
@exception
 +
@see
 +
@author
 +
@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/etc.
+
<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: <code>@param foo the value to convert</code>
+
*Incorrect: <code>@param foo ''T''he value to convert</code>
+
*Incorrect: <code>@param foo the value to convert''.''</code>
+
*Incorrect: <code>@''P''aram foo the value to convert</code>
+
*Incorrect: <code>@param foo''-''the value to convert</code>
+
+
Function that return bool should not use "iff" in @return statements:
+
  
*Correct: <code>@return @c true if button is on and is a toggle button, @c false otherwise</code>
+
; Correct
*Incorrect: <code>@return @c true iff button is on and is a toggle button</code>
+
@param foo the value to convert
 +
; Incorrect
 +
@param foo '''T'''he value to convert
 +
@param foo the value to convert'''.'''
 +
@'''P'''aram foo the value to convert
 +
@param foo'''-'''the value to convert
  
<code>@deprecated</code> should be marked on 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.
+
Functions that return bool should not use "iff" in <tt>@return</tt> statements:
  
=== enum's must be overviewed, and each enumerated value has to be explained===
+
; Correct
 +
@return @c true if button is on and is a toggle button, @c false otherwise
 +
; Incorrect
 +
@return @c true '''iff''' button is on and is a toggle button
  
Same policy as Functions.
+
<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.
  
=== Avoid humour and exclamation marks ===
+
== Document Enumerations ==
 +
 
 +
Enum's must be overviewed, and each enumerated value has to be explained. Same policy as Functions.
 +
 
 +
== Avoid Humour and Exclamation Marks ==
  
 
It is confusing, 'nuff said.
 
It is confusing, 'nuff said.
  
=== 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.
  
=== Run "make apidox" before you commit 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:
 
+
<syntaxhighlight lang="cpp-qt">
/**
+
/**
 
  * @param msecs the number of milliseconds until the timeout
 
  * @param msecs the number of milliseconds until the timeout
 
  *        is signalled
 
  *        is signalled
 
  */
 
  */
void setTimeout(uint msecs, bool repeat)
+
void setTimeout(uint msecs, bool repeat)
 
+
</syntaxhighlight>
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.
 
+
<syntaxhighlight lang="cpp-qt">
/**
+
/**
 
  * @param msecs the number of milliseconds until the timeout
 
  * @param msecs the number of milliseconds until the timeout
 
  *        is signalled
 
  *        is signalled
Line 77: Line 90:
 
  *        @p msecs milliseconds, or just once
 
  *        @p msecs milliseconds, or just once
 
  */
 
  */
void setTimeout(uint, bool)
+
void setTimeout(uint, bool)
 
+
</syntaxhighlight>
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:
  
void setTimeout(uint, bool) { }
+
<syntaxhighlight lang="cpp-qt">virtual void setTimeout(uint, bool) { }</syntaxhighlight>
  
 
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:
  
void setTimeout(uint timeout, bool repeat) { }
+
<syntaxhighlight lang="cpp-qt">virtual void setTimeout(uint timeout, bool repeat) { }</syntaxhighlight>
 
+
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.
+
  
  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 <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.
  { Q_UNUSED(timeout); Q_UNUSED(repeat); }
+
<syntaxhighlight lang="cpp-qt">
 +
  virtual void setTimeout(uint timeout, bool repeat)
 +
{ Q_UNUSED(timeout); Q_UNUSED(repeat); }
 +
</syntaxhighlight>
 +
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.
  
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]]

Revision as of 21:57, 29 June 2011

Classes in the KDE libraries are used by many KDE applications, hence, their usage should be as simple as possible. To help in that endeavor it should be fully documented to let any developer use it. New classes that are added to kdelibs must comply with this doc, all existing classes are grandfathered in, but need to be updated to comply if they do not. The KDE library documention is based upon the Java documentation specification. Follow the link for full in depth documentation about that format.

These guidelines apply not only to classes in kdelibs, but also to libraries elsewhere (KDE PIM, for instance, has a large number of support libraries that need documentation). To some extent they also apply to applications, if only so that it is easier for new developers to contribute meaningfully to the application — well-documented code is easy-to-extend code.

Contents

Add a Class Description

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.

@author should be used to show who the author(s) of the class are. If there are more then one @author tags, \par Maintainer: Foo Bar (foo@bar.com) 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

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 and @endcode should be used to mark code examples.

Example Application

If applicable, provide an example application which shows the usage of the class. A test application or existing application that a developer can reference is an excellent resource for developers looking to learn about the class. This shouldn't be hard because for any class to be in kdelibs it should already exists in two KDE applications.

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 kdelibs/doc/api/ and included by using

\image html myclass.png "Image subtitle"

Qt Designer Integration

If the class exists in Qt Designer, put a 22x20 image in 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

Developers do not read reference documentation like a book, they scan it for the information that they need. This is why it is important that everything is at the place they expect it to be. IDE's might parse the functions and so it is important that the correct meta data is present and not hidden in the description. Function should use the "@" tags in the following order:

@brief
@description
@param
@return
@exception
@see
@author
@since

@param, @return 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
@param foo the value to convert
Incorrect
@param foo The value to convert
@param foo the value to convert.
@Param foo the value to convert
@param foo-the value to convert

Functions that return bool should not use "iff" in @return statements:

Correct
@return @c true if button is on and is a toggle button, @c false otherwise
Incorrect
@return @c true iff button is on and is a toggle button

@deprecated 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

Enum's must be overviewed, and each enumerated value has to be explained. Same policy as Functions.

Avoid Humour and Exclamation Marks

It is confusing, 'nuff said.

Check the Spelling and Grammar

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

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:

/**
 * @param msecs the number of milliseconds until the timeout
 *        is signalled
 */
void setTimeout(uint msecs, bool repeat)

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 @param referring to a parameter that isn't there, add the name for the parameter.

/**
 * @param msecs the number of milliseconds until the timeout
 *        is signalled
 * @param repeat whether the timeout should happen every
 *        @p msecs milliseconds, or just once
 */
void setTimeout(uint, bool)

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:

virtual void setTimeout(uint, bool) { }

This compiles fine; Doxygen will complain about missing names, so you add names:

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 Q_UNUSED macro to deal with this. It "uses" its argument, which shuts the compiler up.

 virtual void setTimeout(uint timeout, bool repeat)
 { Q_UNUSED(timeout); Q_UNUSED(repeat); }

With the function defined like this, both Doxygen and the C++ compiler are happy. Q_UNUSED does not incur any run-time penalty.


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal