[Gajim-devel] Gajim API docs [and thoughts on coding standards and testing]

[Mateusz Biliński]

Hi all.
I'm organizing my development environment for GSoC (and of course
coding in parallel ;) ), so basically what I do is:

1. Writing code.
As the base I use these coding standards:
http://trac.gajim.org/wiki/CodingStandards
Although, I not necessarily agree with all statements [i.e. max length
of line equal to 80 chars (pretty 'oldish' in modern times, 100 or
even more would be probably more reasonable here )] but I'll try to
use them to keep code consistent.

2. Writing tests.
bct has created new directory and already put some testing files in
there for sessions. I've written some simple test file for
PluginManager and probably I'll commit it to my branch very soon.

It would be great to write standards here, too, and/or some kind of
common module (with 'init' function). In example, I use the same code
as bct to update paths (which is required to tests work properly from
this new 'test/' directory). So, this 'paths updating' would be our
common code for starters. It's not much, but maybe later we'll find
more common code to put there.

3. Documenting code [aka 'API docs']
I haven't found any official API docs for Gajim, so I've started
generating them on my own. Here are basic effects:
http://kernel.agh.edu.pl/~vardo/gajim/apidocs/
Maybe it doesn't look pretty, but is very handy and we can fine-tune
it (CSS is our friend).

The biggest advantage here is that we see what is NOT documented.
There's also source code browsing. Imports of modules are also there.
So this may help on generating UML diagrams and other documents
related to Gajim architecture.

What I used to generate docs is *Epydoc*: http://epydoc.sourceforge.net/
This is probably the best docs-generator available for Python.

Config file used to create docs linked above is here:
http://kernel.agh.edu.pl/~vardo/gajim/epydoc.conf

Generally, to generate api docs, in main Gajim's directory, execute:
# epydoc --conf=epydoc.conf
And, that's it. Docs will be in 'apidocs/' directory.

If we decide to document code more, we'll have to choose from three
possible markups:
* epytext: http://epydoc.sourceforge.net/epytextintro.html
* reStructuredText: http://epydoc.sourceforge.net/manual-othermarkup.html
* Javadoc: http://epydoc.sourceforge.net/manual-othermarkup.html
(bottom of page)

Available fields described here: http://epydoc.sourceforge.net/fields.html

Generally, I would opt for epytext (this is default markup) as this is
probably the best implemented one in Epydoc and very similar to
Javadoc, which is probably known to most of us. Or we could use
Javadoc itself. This way, we will be able to use other doc-generators,
like Doxygen.

Of course there's also pydoc, which we might also consider, if it
suits our needs (it's not very sophisticated):
http://docs.python.org/lib/module-pydoc

Here's a comparison of doc-generators:
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
Maybe someone will spot something potentially useful.

Summarizing, the questions is: how should I document my code? :)

Thanks for answers in advance.

-- 
Mateusz Biliński