[sr-dev] Help improving the modules readmes & docs

[Daniel-Constantin Mierla]

Hello,

I thought some people may have spare cycles and are willing to help with 
the documentation. Here is some updates I would like to get for modules:

1) adding ids for parameters, functions, and other sections of the 
docbook xml files. Now we generate the alphabetic indexes pointing to 
the online html readmes, would be better to point directly to the exact 
section. Practically, for example, sections such as next from async module:

    <section>
         <title><varname>workers</varname> (int)</title>

should become:

    <section id="async.p.workers">
         <title><varname>workers</varname> (int)</title>

To get unique ids over all files, I suggest using following pattern:

[module name] [dot] [type] [dot] [title]

The [type] should be:
- p - parameters
- f - functions
- m - mi commands
- r - rpc commands
- s - statistics

2) Add RPC commands to readmes -- some of modules already do, but many 
don't. There is a perl script that should get the list of RPC commands 
from source code, but it requires some patch to a perl lib, not working 
on all systems. Moreover, the output is quite minimalistic, not easy to 
improve the content or add examples. Last generated index is:

- http://www.kamailio.org/docs/docbooks/3.4.x/rpc_list/rpc_list.html

3) Document selects -- although their name are quite suggestive, a bit 
of text around won't harm.

- http://www.kamailio.org/wiki/cookbooks/devel/selects

Because 1) and 2) requires git access, the easiest way to contribute is 
to provide patches to the xml files. If anyone commits to do an 
extensive work on these tasks in short term, we may eventually arrange 
for git access. The 3) is in the wiki, everyone can register an account 
and then update the pages.

I would recommend these guidelines to be followed from now on by 
developers when adding new elements to the module documentation.

Cheers,
Daniel

-- 
Daniel-Constantin Mierla - http://www.asipto.com
http://twitter.com/#!/miconda - http://www.linkedin.com/in/miconda
Kamailio World Conference, April 16-17, 2013, Berlin
  - http://conference.kamailio.com -