FreeTDS Development Group

["Lowden, James K" <LowdenJK AT bernstein.com>]

> From: ZIGLIO Frediano [mailto:Frediano.Ziglio AT vodafoneomnitel.it]
> Sent: March 25, 2003 4:05 AM
>
> Well, Brian start this stuff but may people contributed.

Absolutely true.  I didn't mean to understate your work or anyone else's.  I
just meant that Brian had made the first effort at setting up the Doxygen
framework.  :-)

> If compiled with 1.2.14 version many other functions are 
> taken into account
> (like tds_submit_queryf in libtds/Query). Is possible to 
> reenable these not fully documented function ?
> So we can check reference if a function is not documented...

Doxygen has an option to generate stub documentation for all functions,
whether or not they contain specially-formatted comments.  To do that, set
the EXTRACT_ALL tag in tds.dox to YES. I didn't do that because that setting
suppresses warnings about undocumented members.  It's really two ways of
looking at the same thing.  

To find all the functions to document, here's what I did.  

1.  Add a little template comment block before each function definition.  
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.  
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.)

It would be worthwhile to define more groups; they drive the module
organization.  We need ct-lib, ct-blk, cs-lib.  ODBC probably needs several
subgroups, too.  That would give the reference manual more structure, and
make it into more of an outline.  I hadn't gotten that far yet.  

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

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, 

--jkl


The information contained in this transmission may contain privileged and
confidential information and is intended only for the use of the person(s)
named above.  If you are not the intended recipient, or an employee or agent
responsible for delivering this message to the intended recipient, any
review, dissemination, distribution or duplication of this communication is
strictly prohibited. If you are not the intended recipient, please contact
the sender immediately by reply e-mail and destroy all copies of the
original message. Please note that we do not accept account orders and/or
instructions by e-mail, and therefore will not be responsible for carrying
out such orders and/or instructions.