Changes

== 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.

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.

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 ==

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.

 

 

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

<code>

<code>