RE: help: tips from c++ api writers

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Hi Carol,

I concur with Megan about using tools to document code.

I'm using Doxygen at my company, as well. I'm really impressed with what it
does, particularly in the light of the alternative -- doing it by hand.

I'd be happy to share insight about using Doxygen.

I have to admit that your deliverables can be improved if you have a
programmer on your staff who can devote a week or two to writing scripts for
tweaking the output.

For example, part of our code pool exposes source code, while part only
exposes the function calls. I have to run Doxygen multiple times, meaning
multiple mini-HTML systems. Moreover, the theory of operation and usage is
written in FrameMaker and exported using Mif2Go, yet another mini-HTML
system.

There are many ways to wrap these into what looks like a comprehensive help
system. Both Doxygen and Mif2Go allow you to enter information such as
headers and footers when topics are generated. It wouldn't be too difficult
to have these point to some manually generated main pages to pull everything
together.

I will say that the route I chose was to do some Perl script programming
myself. I have Doxygen and Mif2Go insert HTML comments (special tags) that
my Perl scripts recognize. Once the HTML files are generated, I run my
scripts on them to swap out the information between the tags with what I
want. This way, if my co-workers don't like the navigation I created, my
CSS, the copyright notice at the bottom of each topic, etc., I can swap
these out for the entire system without pain. I can also generate main pages
from what is actually in the system, in addition to fixing relative paths.

I also use Perl to implement some input filters. One of the simple filters
changes the Doxygen @bug tag (which expands into "Bugs and Limitations") to
a new @lim tag (which expands into "Limitations and Caveats"). It isn't a
good idea to deliver any help system that uses the word "Bugs" frequently. A
slightly more complex filter I have turns our scripting language into
something more C++ so that it can be run through Doxygen, too.

Enough technical details for now. More important than this is getting true
buy-off from development. We were lucky in that our coding convention
document was five years old and due for an update. Our engineering director
(who is also my manager) set up a working group to update the conventions. I
was able to participate and get Doxygen related changes implemented for
doing code comments. This was the hardest aspect of the whole coding
convention task and garnered the most resistence. (Surprise, surprise.) But
I got what I wanted (e.g., the use of @ingroup for better chunking of the
material). And slowly but surely, development is getting better commented
source code.

You didn't mention what short notice really means. You'll need some time to
experiment with Doxygen. The output from Doxygen is pretty damn good even if
there are not Doxygen formatted comments in the code. However, once you (get
permission to) start re-formatting or outright adding Doxygen comments to
the code, you'll need time for multiple passes to see what format looks
best, to convert exist comments, to flag non-existent comments for
developments help, and to proof what development wrote.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com




> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of Carol Chung
> Sent: Wednesday, April 04, 2001 7:08 PM
> To: TECHWR-L
> Subject: help: tips from c++ api writers
>
>
> Hi,
>
> I don't really know c++ but was asked to document an api on short notice.
> I'm expecting some info from the developer but don't know how much detail
> he'll provide. If I have to, I heard that you can extract info
> from header
> files. Do you know what the file extension for those are? Do you have any
> sample header file to show me what I should look for? A fake
> example would
> be fine.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.