Documentation Team/API Documentation - Revision history

FGrose: categorize

2011-11-02T19:34:12Z

categorize

← Older revision		Revision as of 15:34, 2 November 2011
Line 1:		Line 1:
	{{draft}}		<noinclude>[[Category:API]]
			[[Category:Documentation]]
			</noinclude>{{draft}}
	== Definition ==		== Definition ==

Line 425:		Line 427:
	:This is a list of all available documentation tags of doxygen, from the official site. Note that the list uses a backslash in front of a tag, while this page always used the at sign. Both are allowed, but for KDE you should use the at sign to stay consistent within KDE.		:This is a list of all available documentation tags of doxygen, from the official site. Note that the list uses a backslash in front of a tag, while this page always used the at sign. Both are allowed, but for KDE you should use the at sign to stay consistent within KDE.
	-->		-->
	~~[[Category:Documentation]]~~

Cjl: moved Walter is a wanker 9/API Documentation to Documentation Team/API Documentation over redirect: revert

2010-02-25T00:15:02Z

moved Walter is a wanker 9/API Documentation to Documentation Team/API Documentation over redirect: revert

← Older revision		Revision as of 20:15, 24 February 2010
(No difference)

Faggot: moved Documentation Team/API Documentation to Walter is a wanker 9/API Documentation: Walter is a wanker

2010-02-24T23:47:35Z

moved Documentation Team/API Documentation to Walter is a wanker 9/API Documentation: Walter is a wanker

← Older revision		Revision as of 19:47, 24 February 2010
(No difference)

Dfarning: fix broken links

2009-04-09T04:52:18Z

fix broken links

FGrose: DocumentationTeam/API Documentation moved to Documentation Team/API Documentation: deCamel casing

2009-03-17T20:58:58Z

DocumentationTeam/API Documentation moved to Documentation Team/API Documentation: deCamel casing

← Older revision		Revision as of 16:58, 17 March 2009
(No difference)

Dfarning: DevelopmentTeam/Tutorials/API Documentation moved to DocumentationTeam/API Documentation: API documentation is significant enough to warrant a place in the doc team root.

2008-06-28T17:58:19Z

DevelopmentTeam/Tutorials/API Documentation moved to DocumentationTeam/API Documentation: API documentation is significant enough to warrant a place in the doc team root.

← Older revision		Revision as of 13:58, 28 June 2008
(No difference)

Dfarning: editing Writing APIDOX in New Code

2008-06-15T00:19:45Z

editing Writing APIDOX in New Code

@@ Line 1: / Line 1: @@
 == Definition ==
@@ Line 126: / Line 127: @@
    //DOXYGEN_EXCLUDE
 </code>
 *Every module should have a module comment.
@@ Line 138: / Line 138: @@
 </code>
-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 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.
 '''3. Watch this space!'''

Dfarning: editing Writing APIDOX in New Code

2008-06-14T21:27:11Z

editing Writing APIDOX in New Code

← Older revision		Revision as of 17:27, 14 June 2008
Line 114:		Line 114:
	Packages are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the package as you go along. This means:		Packages are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the package as you go along. This means:

	*Every package should have a package~~-level~~ comment.		*Every package should have a package comment.
	In the root directory of your packages create a file named Mainpage.dox. The first line of the comment must be the @mainpage doxygen directive followed by your package name. Next is the package comment wrapped in a docstring. Last are some apidox variables which help define the menu structure.		In the root directory of your packages create a file named Mainpage.dox. The first line of the comment must be the @mainpage doxygen directive followed by your package name. Next is the package comment wrapped in a docstring. Last are some apidox variables which help define the menu structure.

	<code>		<code>
	# @mainpage ~~sugar~~		# @mainpage Sugar
	<nowiki>"""</nowiki>		<nowiki>"""</nowiki>
	Here is the description of the package named sugar.		Here is the description of the package named sugar.
Line 128:		Line 128:


			*Every module should have a module comment.
			A given module only needs a comment once in your source tree (or within one bunch of files that generate apidox together). Near the top of each module __init__.py file, create a @mainpage <module_name> directive followed by a description of what the module is for and what it defines. Wrap this up in docstring.

	*Every module should have a module~~-level comment~~.		<code>
			<nowiki>"""</nowiki>
			@mainpage Control Panel
			Here is a description of the module named controlPanel.
			<nowiki>"""</nowiki>
			</code>

	~~Nnear the top of your __init__.py file, write down what the module is for, vaguely what it defines. Wrap this up in a """ @namespace """ comment and you are set.~~		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 module should have a comment. A given moduel 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>		<code>

Dfarning: editing Writing APIDOX in New Code

2008-06-14T20:23:40Z

editing Writing APIDOX in New Code

← Older revision		Revision as of 16:23, 14 June 2008
Line 101:		Line 101:

	== Writing APIDOX in New Code ==		== Writing APIDOX in New Code ==
	~~<!--~~
	The following little checklist should get you through the worst of writing apidox.		The following little checklist should get you through the worst of writing apidox.

	'''1. Write apidox as you code'''		'''1. Write apidox as you code.'''

	The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.		The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.
Line 110:		Line 110:
	This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.		This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.

	'''2. Document your ~~modules~~ completely'''		'''2. Document your packages completely'''

			Packages are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the package as you go along. This means:

			*Every package should have a package-level comment.
			In the root directory of your packages create a file named Mainpage.dox. The first line of the comment must be the @mainpage doxygen directive followed by your package name. Next is the package comment wrapped in a docstring. Last are some apidox variables which help define the menu structure.

			<code>
			# @mainpage sugar
			<nowiki>"""</nowiki>
			Here is the description of the package named sugar.
			<nowiki>"""</nowiki>
			//DOXYGEN_SET_PROJECT_NAME=Sugar
			//DOXYGEN_NAME=Sugar-module
			//DOXYGEN_EXCLUDE
			</code>



			*Every module should have a module-level comment.

	Modules are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the module as you go along. This means:

	*Every module should have a module-level comment. Nnear the top of your __init__.py file, write down what the module is for, vaguely what it defines. Wrap this up in a """ @namespace """ comment and you are set.		Nnear the top of your __init__.py file, write down what the module is for, vaguely what it defines. Wrap this up in a """ @namespace """ comment and you are set.
	*Every module should have a comment. A given moduel 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 module should have a comment. A given moduel 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:

Line 151:		Line 169:

	== Fixing APIDOX in Old Code ==		== Fixing APIDOX in Old Code ==
			<!--
	Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)		Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

Dfarning: editing APIDOX Basics

2008-06-14T19:58:22Z

editing APIDOX Basics

← Older revision		Revision as of 15:58, 14 June 2008
Line 1:		Line 1:
	== Definition ==		== 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 (''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.

Line 6:		Line 6:

	Good apidox take some effort to write -- but less effort 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) code.		Good apidox take some effort to write -- but less effort 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) code.
	~~-->~~
	== Preamble ==		== Preamble ==
	~~<!--~~
	APIDOX are what make a program accessible to other contributors. They are not essential, but they certainly help a great deal for new people who want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.		APIDOX are what make a program accessible to other contributors. They are not essential, but they certainly help a great deal for new people who want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.

Line 16:		Line 16:

	This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to write apidox.		This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to write apidox.
	~~-->~~
	== APIDOX Basics ==		== APIDOX Basics ==

Line 25:		Line 25:
	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.

	APIDOX ~~are written in~~ python ~~docstring comments~~. These ~~comments~~ are surrounded by <nowiki>"""</nowiki> (quote, quote, quote) -- 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 <nowiki>"""</nowiki> and <nowiki>"""</nowiki>, like this:		APIDOX consist of two types of comments python docstrings and doxygen directives. These docstrings are surrounded by <nowiki>"""</nowiki> (quote, quote, quote) -- 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.

			Doxygen directives are one line comments preceded by a #. They are short statments that help Doxygen determine the organization of your package.

			But documentation can be very straightforward: just write down what a method does, surrounded by <nowiki>"""</nowiki> and <nowiki>"""</nowiki>, like this:

	<code>		<code>

← Older revision		Revision as of 00:52, 9 April 2009
Line 149:		Line 149:
	'''4. Write a main page for your application.'''		'''4. Write a main page for your application.'''

	This is usually done in a separate file ~~{{path\|Mainpage.dox}}~~ in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.		This is usually done in a separate file in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

	== Fixing APIDOX in Old Code ==		== Fixing APIDOX in Old Code ==
Line 380:		Line 380:
	Very useful, in fact, for the reader who is wondering		Very useful, in fact, for the reader who is wondering
	how exactly to use the class in a straightforward way.		how exactly to use the class in a straightforward way.
	Most classes ~~in {{path\|kdelibs/kdecore}}~~ have example code.		Most classes have example code.

	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
Line 396:		Line 396:
	</code>		</code>

	This is how most of the examples ~~in {{path\|kdelibs}}~~		This is how most of the examples
	are done, actually. It works reasonably well, you can pare the		are done, actually. It works reasonably well, you can pare the
	example down to something really minimal and leave out all the		example down to something really minimal and leave out all the