On 21-04 08:36, Juha Heinanen wrote:
Klaus Darilion writes:
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
i agree and also, there should be a common format for readme file source files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc auth_radius_admin.xml auth_radius.xml
there is thus need to standardize doc format and have documentation of all common modules up to data, before we can even dream to announce this project to users.
It does not really matter how many files there are. In both cases it is xml based docbook that is used to produce a single document.
The only structure difference I can see is that we start our docbook tree with a <section> element, while kamailio modules start with <book>. This only makes a difference if you process the sources within a larger collection, i.e. we wanted to be able to insert module documentation within a larger document and starting with <section> is more flexible there because you can insert it anywhere in the documentation tree.
But in most cases the documentation in each module is processed separatetely and most often it is used to generate README files, and there it does not matter if the document starts with <section> or <book>.
The fact that ser modules sometimes lack up-to-date documentation is another issue.
Jan.