[Kamailio-Devel] RFC: database interface module infrastructure

Carsten Gross carsten.gross at 1und1.de
Tue Aug 12 13:50:54 CEST 2008


Hi Henning,

Am Dienstag 12 August 2008 13:07:53 hast Du folgendes geschrieben:
> On Tue, August 12, 2008 12:46 pm, Carsten Gross wrote:
> > This way you get the documentation, the necessary data structures and so
> > on correct without the possibility to forget something - less bugs, no
> > repetitive coding.
> >
> > A small disadvantage is that it is quite uncommon to have typical source
> > code files autogenerated from xml. An extra warning ("Do not edit this
> > file, edit ... instead and generate this file with blablubb") should be
> > included in all autogenerated files, especially if they have a common
> > ending like .h or .c.
>
> thank you for the reply. Yes, this are exactly the advantages i have in my
> mind too. There is already a warning like this in my proposal (see my
> initial mail), please let me know if you have something other/ more
> visible in your mind.

As it is not a common step to have a file like this being autogenerated in 
my opinion it should be more visible that it makes no sense to edit the .h 
file. Also there is often some fear of contact concerning xml. 
Therefore the comment in the generated source should make clear: 

- changes done in the .h file are really useless and will be lost
- xml/xslt is easy ;-), there is help how to get this file from xml source

I could think of something like the following text below at the start of the 
autogenerated file. Instead of the < ... > statements the real pathes, tools 
or commands should be given in the generated comments.

@cond, @endcond is for doxygen. This way the "ugly" comment is not listed in 
doxygen documentation. 

#CITE BEGIN
/*!
 * \file auth_db.h
 * \brief Database support for modules.
 *
 * Database support functions for modules.
 *
 * @cond
 * @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 * @                            WARNING                                   @
 * @ This file was autogenerated from the XML source file                 @
 * @ <full-path-in-project>/kamailio-auth_db.xml. It can be               @
 * @ regenerated                                                          @
 * @ by running <command to generate the file out of the .xml source>     @
 * @ Make sure you have <necessary tools here> installed.                 @
 * @                                                                      @
 * @ ALL CHANGES DONE HERE WILL BE LOST IF FILE IS REGENERATED            @
 * @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 * @endcond
#END

Regards,

   Carsten



More information about the Devel mailing list