FreeTDS Development Group

[ZIGLIO Frediano <Frediano.Ziglio AT vodafoneomnitel.it>]

> 
> To find all the functions to document, here's what I did.  
> 
> 1.  Add a little template comment block before each function 
> definition.  

Good idea!

> 2.  Run Doxygen, redirecting stderr to a log file.  
> 3.  Use Perl to reformat the resulting Doxygen warnings into doxygen
> comments.  Most of the warnings had to do with missing 
> parameters.  It was a
> simple thing to convert them into "\param" lines.  

You know... I'm not a Perl guru, you seem to be the Perl guru of group...

> 4.  Cut, paste, embellish, repeat.  Several nights of that.  
> 5.  Review the code for any remaining unexpanded template 
> comment blocks.  
> 
> The list of warnings is still quite long, because we have 
> many undocumented
> structures and enumerations.  
> 
> (I'm not sure I answered your question.  I don't see any 
> documentation block
> anywhere for tds_submit_queryf.)
> 

I know, there isn't documentation but doxygen 1.2.14 and 1.2.15 seem to
document it.

... omissis ...

> I've been thinking of adding a file "dox.h" that would be nothing but
> doxygen comments, to remove some of the more verbose and 
> arcane doxy stuff
> from the source code.  For instance, in src/dblib/dblib.c, we have: 
> 
> /**
>  * @file dblib.c
>  * Main implementation file for \c db-lib.
>  */
> /**
>  * @file bcp.c
>  * Implementation of \c db-lib bulk copy functions.
>  */
> /**
>  * \defgroup dblib_api db-lib API
>  * Functions callable by \c db-lib client programs
>  *
>  * The \c db_lib interface is implemented by both Sybase and 
> Microsoft.
> FreeTDS
>  seeks to implement
>  * first the intersection of the functions defined by the vendors.
>  */
> /**
>  * \ingroup dblib_api
>  * \defgroup dblib_internal db-lib internals
>  * Functions called within \c db-lib for self-help.
>  */
> 

You can put bcp.c comment in bcp.c. I don't like idea of a file only to
store documentation structure... If someone want to submit a patch it should
skip comment or if it know doxygen it can just fill documentation blanks...

> which isn't exactly adding clarity to the source code.  I'm 
> not sure what's
> the best way to handle that, and I don't like to add files to 
> the source
> tree unless I'm sure they'll be useful.  
> 
> Regards, 
> 

It's just like if (5 == whatever) instead of if (whatever == 5) or use for
in strange way... syntax is syntax... 

Does anyone like -dj option in our .indent.pro? This strange option (not
documented in my manual page) seem to have different behavior in different
indent version (I noted this after your reindentation...)

freddy77

=================================
"STRICTLY PERSONAL AND CONFIDENTIAL

This message may contain confidential and proprietary material for the sole
use of the intended recipient. Any review or distribution by others is
strictly prohibited. If you are not the intended recipient please contact
the sender and delete all copies.
The contents of this message that do not relate to the official business of
our company shall be understood as neither given nor endorsed by it."

=================================