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

[Yann Le Boulanger]

Mateusz Biliński <mateusz.bilinski at gmail.com> a écrit :

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

Yes please, it's really easier when coding in console.

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

I haven't looked at that code yet, but having common code for all test  
program sounds a must.

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

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

Great, I'll add that to website !

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

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

We indeed DO need to document our code more properly.
Using epydoc syntax sounds logic, but the ability to use doxygen is  
nice. It seems to support more features.

> Summarizing, the questions is: how should I document my code? :)
>
> Thanks for answers in advance.

I would vote for epydoc syntax. If we really need doxygen one day it  
seems easy to switch to javadoc.
-- 
Yann

----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.