[OT]: Doxygen, source documentor

[hua]

Hi guys,
I'm wondering what technique do you guys employ with regards to documenting one's source? I've read about Doxygen and was very interested in it but alas it doesn't support xBase dialect.

I think if such a tool is available it'd make our lives a whole lot easier since it can even auto generate class hierarchy for us if it exist.

Thoughts?

[James Bott]

Hua,

There is a very old dBase source documentor program called Snap! Have you seen this? You can get a free copy here:

http://www.the-oasis.net/ftpmaster.php3 ... putils.htm

It is almost at the bottom of the page. Look for: snp502.zip

James

[hua]

Thanks for the rec James. I'd gone through its documentation and it states that some newer Clipper syntax might not be processed correctly which makes me wonder whether it would actually be able to process prgs that makes use of OOP and new extensions that exist in [x]Harbour.

[James Bott]

Hua,

The newer Clipper sntax that it doesn't handle are codeblocks and multiple commands on the same line--probably stuff that is not too important.

You can also add new syntax in a file called personal.key--check the docs for more info.

Granted it is not perfect, but it is still useful, and certainly better than nothing.

James

[xProgrammer]

Hua

I'm not sure exactly what features of Doxygen you wanted. But it seems to me that we might be able to build some code snippets for documenting xBase code in xBase itself. I think that any such system would, for many of its features at least, be highly dependant upon the programmer's programming styles and conventions and rely upon them being applied fairly consistently. Any such system is likely to work much more effectively with code that was written to be documented by a given documentation software than try to retro document a given piece of code.

I am currently doing some design work on the extension of a software system written in Java with a SQL Server or Sybase (optional) back end. I wrote a program (in xHarbour / FiveLinux) to document the database structure. The output was a series of HTNL pages (1 per table) plus a contents page. The input was the database script generated from SQL Server. It showed the structure of each table (fieldname, type, length where not determined by type, whether nullable, if it was a primary key, and if it was a secondary key what table the secondary key pointed to. It also listed what other tables had secondary keys pointing to this table. The information about key relationships was only able to be worked out because the client (mostly) used a consistent, logical naming scheme - actually a slight modification of what I use myself. I use it for xBase tables too - although programmers who use aliasing might think it unnecessarily wastes characters in fieldnames it has the advantage of guaranteeing unique fieldnames when porting.

The basic idea is that all table names have a prefix (I use 2 letters but the client sometimes uses more) followed by an underscore and the tablename. For example a table of doctors in a medical system might be

DO_DOCTOR.dbf

Then all the fields in DO_DOCTOR would have the same prefix. The primary key (which I generate in xBase but of course SQL does it for you - but with problems) would be

DO_KEY

My DO_DOCTOR doesn't need a secondary key but lets say it did - doctors belong to hospitals for instance. If my hospital file was HO_HOSPITAL then such a seconadry key in DO_DOCTOR would be

DO_HOKEY

I then just avoid having any other fieldnames ending xxKEY. You can see that given this type of naming convention it isn't very difficult to write a program that generates documentation on your table structures.

I should note also that to simplify (and beautify) programmatic table creation I wrote a set of preprocessor commands so that

I didn't have to repeatedly type the same prefix

I didn't have to use less than intuitive arrays in my code such as { "DO_KEY", "C", 16, 0 }

I didn't have to define lengths and decimals where they are implied by the type anyway

I could support my own "types" (even if they aren't reflected in the created table)

So for example to create a (very simple) DO_DOCTOR table my code might be:

DEFINE xTABLE DOCTOR PREFIX DO_
xKEY KEY
xKEY HOKEY
xSTRING SURNAME LENGTH 32
xSTRING GVNNAME LENGTH 32
xDATE DOB
xCHAR CODE
CREATE TABLE

Since all my keys are type "C" length 16 decimals 0 the preprocessor can fill that out. Similarly it knows xSTRING maps to type "C" which needs a length but decimals again are 0. xDATE maps to type "D" (length 8, decimals 0). xCHAR is just my single cahracter type - ie shorthand for type "C" length 1 decimals 0. I think its a lot neater and what's more a lot less to type!

This post is getting a bit too long so just a bit about documenting code for now.

xBase code should be very easy for a code documenter to navigate and understand however depending upon what you want out of the documenter, the fact that it is weakly typed might be a major stumbling block.

I would be happy to extend discussion on these types of issues if others are interested, and happy to share any code too if its of any use.

Happy coding!

xProgrammer