Development/Tutorials/API Documentation - Revision history

Claus chr: Box template should not be used anymore

2012-08-27T17:19:46Z

Box template should not be used anymore

AnneW at 12:29, 13 July 2012

2012-07-13T12:29:12Z

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


2011-06-29T19:25:24Z
Text replace - "<code cpp>" to "<syntaxhighlight lang="cpp">"

				
				
				
				
			
			← Older revision
			Revision as of 19:25, 29 June 2011
			
Line 324:
Line 324:
    
  Example:   Example:
− <code cpp> + <syntaxhighlight lang="cpp">
  /**   /**
    * This class emulates a Moose.     * This class emulates a Moose.
Line 335:
Line 335:
    
  Example:   Example:
− <code cpp> + <syntaxhighlight lang="cpp">
  /**   /**
    * This class emulates a Moose.     * This class emulates a Moose.

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

2011-06-29T19:16:00Z

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

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


2011-06-29T19:13:38Z
Text replace - "<code cppqt>" to "<syntaxhighlight lang="cpp-qt">"

				
				
				
				
			
			← Older revision
			Revision as of 19:13, 29 June 2011
			
Line 30:
Line 30:
  APIDOX are written in special comments. These comments start with /** (slash, star, star) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup. But documentation can be very straighforward: just write down what a method does, surrounded by /** and */, like this:   APIDOX are written in special comments. These comments start with /** (slash, star, star) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup. But documentation can be very straighforward: just write down what a method does, surrounded by /** and */, like this:
    
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /** This method increases the sexyness of Kontact and should as   /** This method increases the sexyness of Kontact and should as
    * such be called whenever possible (i.e. instead of having idle     * such be called whenever possible (i.e. instead of having idle
Line 44:
Line 44:
  For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:   For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:
    
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /** Namespace for KDE network-related classes */   /** Namespace for KDE network-related classes */
  namespace KDENetwork {   namespace KDENetwork {
Line 84:
Line 84:
  *Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.   *Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
  *Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments.<br />Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:   *Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments.<br />Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
− <code cppqt>/** The Ungulate namespace collects classes and methods + <syntaxhighlight lang="cpp-qt">/** The Ungulate namespace collects classes and methods
  pertaining to hooved animals. */   pertaining to hooved animals. */
    
Line 90:
Line 90:
  </code>   </code>
  :In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).   :In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /** The Ungulate namespace collects classes and methods   /** The Ungulate namespace collects classes and methods
  pertaining to hooved animals. */   pertaining to hooved animals. */
Line 101:
Line 101:
  *Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.   *Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
  *Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive.<br />For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past.<br />It looks like this:   *Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive.<br />For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past.<br />It looks like this:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  enum State {   enum State {
     none,    /**< No bracket seen */      none,    /**< No bracket seen */
Line 139:
Line 139:
  '''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.   '''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.
    
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /** @file   /** @file
    * This file is part of AnApplication and defines     * This file is part of AnApplication and defines
Line 150:
Line 150:
  '''Documentation for a namespace:'''   '''Documentation for a namespace:'''
    
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /**   /**
    * This namespace collects functions related to     * This namespace collects functions related to
Line 159:
Line 159:
  '''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.   '''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.
    
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /**   /**
    * This class represents a Moose in the woodland     * This class represents a Moose in the woodland
Line 175:
Line 175:
  '''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.     '''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.  
    
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /**   /**
    * This method names a particular Moose and as a side effect     * This method names a particular Moose and as a side effect
Line 242:
Line 242:
  and case-sensitivity! -- and then the description. The description can   and case-sensitivity! -- and then the description. The description can
  span multiple lines.   span multiple lines.
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /** Calculate the root-mean-square distance from the   /** Calculate the root-mean-square distance from the
    * origin to the given integral coordinate.     * origin to the given integral coordinate.
Line 268:
Line 268:
  of a parameter (or anything else, really, but it only makes sense in front   of a parameter (or anything else, really, but it only makes sense in front
  of a name of a parameter). Like this:   of a name of a parameter). Like this:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /** Calculate the root-mean-square distance from the origin to   /** Calculate the root-mean-square distance from the origin to
    * the given integral coordinate which is given as a pair @p x,     * the given integral coordinate which is given as a pair @p x,
Line 299:
Line 299:
  element that may be replaced in a method call or string or something, so   element that may be replaced in a method call or string or something, so
  it crops up all the time. You know, you write some thing like this:   it crops up all the time. You know, you write some thing like this:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /** This method connects to a database. The connection string is   /** This method connects to a database. The connection string is
    * composed of a username, password, host and database name as     * composed of a username, password, host and database name as
Line 352:
Line 352:
  One way to write example code is to use @code and @endcode around   One way to write example code is to use @code and @endcode around
  blocks of example code in the Doxygen comments themselves, like this:   blocks of example code in the Doxygen comments themselves, like this:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  /**   /**
    * This class represents a Moose.     * This class represents a Moose.



Nicolas17: /* Common Pitfalls */ proper m-dashes
2010-04-01T16:33:02Z
‎Common Pitfalls:  proper m-dashes

				
				
				
				
			
			← Older revision
			Revision as of 16:33, 1 April 2010
			
Line 223:
Line 223:
  I'm not sure about anonymous namespaces.   I'm not sure about anonymous namespaces.
    
− For file-scoped functions -- that is, functions + For file-scoped functions &mdash; that is, functions
  that are defined in a file, not in a namespace   that are defined in a file, not in a namespace
− and not in a class, + and not in a class &mdash;
  you ''must'' document the file   you ''must'' document the file
  they are in. This applies mostly   they are in. This applies mostly



Nicolas17: /* Common Pitfalls */ Fix newline in note box
2010-04-01T16:31:18Z
‎Common Pitfalls:  Fix newline in note box

				
				
				
				
			
			← Older revision
			Revision as of 16:31, 1 April 2010
			
Line 228:
Line 228:
  you ''must'' document the file   you ''must'' document the file
  they are in. This applies mostly   they are in. This applies mostly
− to files which collect a bunch of non-method utility functions.}} + to files which collect a bunch of non-method utility functions.
  + }}
    
  '''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document <em>none</em> of them, or you can document   '''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document <em>none</em> of them, or you can document



Pippin: /* APIDOX Basics */
2009-01-02T19:00:26Z
‎APIDOX Basics

				
				
				
				
			
			← Older revision
			Revision as of 19:00, 2 January 2009
			
Line 24:
Line 24:
  {{Tip|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}   {{Tip|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}
    
− {{Tip|If you do have Doxygen installed and want to build the apidox, use the kdedoxygen.sh script as described in [[Development/Tools/apidox|apidox]].}} + {{Tip|If you do have Doxygen installed and want to build the apidox, use the method described in [[Development/Tools/apidox|apidox]].}}
    
  Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.   Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.



Argonel: /* Links */
2008-11-21T21:55:18Z
‎Links

				
				
				
				
			
			← Older revision
			Revision as of 21:55, 21 November 2008
			
Line 388:
Line 388:
    
  == Links ==   == Links ==
  + 
  + [[Development/Tools/apidox|How to build apidox]]
    
  [http://www.stack.nl/~dimitri/doxygen/commands.html List of supported doxygen tags]   [http://www.stack.nl/~dimitri/doxygen/commands.html List of supported doxygen tags]



Mpyne: Add link to kdedoxygen.sh description for API Documentation tutorial
2008-06-24T01:46:08Z
Add link to kdedoxygen.sh description for API Documentation tutorial

				
				
				
				
			
			← Older revision
			Revision as of 01:46, 24 June 2008
			
Line 24:
Line 24:
  {{Tip|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}   {{Tip|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}
    
  + {{Tip|If you do have Doxygen installed and want to build the apidox, use the kdedoxygen.sh script as described in [[Development/Tools/apidox|apidox]].}}
    
  Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.   Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

@@ Line 1: / Line 1: @@
 __TOC__
-{{Box|Definition|
+{{Info|2=Definition|
 '''API (''Application Programming Interface'') documentation''' is documentation that applies to ''a program'' and its interfaces. It is documentation that explains to a developer who is going to work with the program, or a developer who is going to work on a program, how things work and what methods are there to call.
 API documentation is sometimes called an API reference manual. It needn't ''just'' be a reference manual, though, there can be extensive additional material, like tutorials, histories, etc. In this page, we will refer to all the material that documents and explains the API of a piece of code as "apidox."
-Good apidox take some effort to write -- but I would say less than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) C code.|100%}}
+Good apidox take some effort to write -- but I would say less than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) C code.}}
 == Preamble ==

@@ Line 1: / Line 1: @@
-{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
 __TOC__
 {{Box|Definition|

@@ Line 40: / Line 40: @@
   */
 void incSexyness(KInstance *instance);
-</code>
+</syntaxhighlight>
 For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:
@@ Line 56: / Line 56: @@
    };
+}
-</code>
+</syntaxhighlight>
 You can see here that each nesting level of "things" is documented with a comment -- the namespace, the class and the method. Things that are private do not need apidox, but things that are protected do.
@@ Line 88: / Line 88: @@
 namespace Ungulate {
-</code>
+</syntaxhighlight>
 :In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
 <syntaxhighlight lang="cpp-qt">
@@ Line 95: / Line 95: @@
 class Mammal;
 namespace Ungulate {
-</code>
+</syntaxhighlight>
 :There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
 *Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly).<br />The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
@@ Line 108: / Line 108: @@
    dquote   /**< Found double quotes */
 };
-</code>
+</syntaxhighlight>
 '''3. Watch this space!'''
@@ Line 146: / Line 146: @@
   * @author Mostly by me
   */
-</code>
+</syntaxhighlight>
 '''Documentation for a namespace:'''
@@ Line 155: / Line 155: @@
   * counting and enumeration of mammals and their limbs.
   */
-</code>
+</syntaxhighlight>
 '''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.
@@ Line 171: / Line 171: @@
   * @since  3.5
   */
-</code>
+</syntaxhighlight>
 '''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.
@@ Line 193: / Line 193: @@
   */
 bool name(const QString &name, bool santa = false);
-</code>
+</syntaxhighlight>
 Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.
@@ Line 250: / Line 250: @@
   * @param x x-coordinate
   */
-</code>
+</syntaxhighlight>
 When you document all the parameters like this, Doxygen will complain if
@@ Line 275: / Line 275: @@
   */
 double distance(int x, int y, bool nonFree=false);
-</code>
+</syntaxhighlight>
 '''Misuse of tags in running text:''' This boils down to the warning
@@ Line 307: / Line 307: @@
   * @return true if the connection succeeded.
   */
-</code>
+</syntaxhighlight>
 This bit of dox is terribly broken, because the whole sample connection
@@ Line 330: / Line 330: @@
   *     with next-generation mooses.
   */
-</code>
+</syntaxhighlight>
 '''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.
@@ Line 341: / Line 341: @@
   *     @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
   */
-</code>
+</syntaxhighlight>
 == Code Examples in APIDOX ==
@@ Line 362: / Line 362: @@
   * @endcode
   */
-</code>
+</syntaxhighlight>
 This is how most of the examples in {{path|kdelibs}}

← Older revision		Revision as of 21:55, 21 November 2008
Line 388:		Line 388:

	== Links ==		== Links ==
		+
		+	[[Development/Tools/apidox\|How to build apidox]]

	[http://www.stack.nl/~dimitri/doxygen/commands.html List of supported doxygen tags]		[http://www.stack.nl/~dimitri/doxygen/commands.html List of supported doxygen tags]

← Older revision		Revision as of 01:46, 24 June 2008
Line 24:		Line 24:
	{{Tip\|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}		{{Tip\|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}

		+	{{Tip\|If you do have Doxygen installed and want to build the apidox, use the kdedoxygen.sh script as described in [[Development/Tools/apidox\|apidox]].}}

	Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.		Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

Development/Tutorials/API Documentation - Revision history

Claus chr: Box template should not be used anymore

AnneW at 12:29, 13 July 2012

Neverendingo: Text replace - "" to ""

Neverendingo: Text replace - "" to ""

Neverendingo: Text replace - "" to ""

Nicolas17: /* Common Pitfalls */ proper m-dashes

Nicolas17: /* Common Pitfalls */ Fix newline in note box

Pippin: /* APIDOX Basics */

Argonel: /* Links */

Mpyne: Add link to kdedoxygen.sh description for API Documentation tutorial

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

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

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