[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

(summary) c++ api help: extraction tools

Subject: (summary) c++ api help: extraction tools
From: "Carol Chung" <cychung55 -at- hotmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 09 Apr 2001 12:42:56 -0700

Hi, these are recommended extraction tools for writing c++ api documentation. Thanks again. -Carol Chung

---

replies begin

Carol,

There are extraction tools for this. Do not do it yourself. Buy a tool and
use it. Unfortunately, I don't have a recommendation, but all
object-oriented languages have extractors. Your programmers probably already
have one. Try looking at tucows.com, or C/C++ magazine ads.

After you have used the tool, you may want to provide more access methods
into the content, as the extracted content tends to be hierarchical, which
forces programmers to know where to look. An alphabetic index would be
helpful to the programmers.

David

---

Carol et al,

I would recommend an automated tool for extracting documentation
directly from the code. At my company, the developers have
installed and are using doxygen
(http://www.stack.nl/~dimitri/doxygen/). Doxygen is free soft-
ware (GUN License).

In the past, when I documented a small API, I found the biggest
challenges were in making sure my documentation was complete and
accurate. This is very tedious work and the best you'll get the
best results when information is taken directly from the code.
Fortunately, tools like doxygen and javadoc
(http://java.sun.com/j2se/javadoc/index.html) make API documen-
tation much easier.

Good luck with your project!

Regards,
Megan Golding
SecureWorks, Inc.

---

I agree with Megan Golding about using a source code extractor tool.

Our programming is done in C and we also use Doxygen to extract the API
reference from the source. It makes a lot of difference to do it this way
although it does take quite a lot of time to set up, but it's time worth
spending.

From Doxygen we then use HTML Help Workshop to convert the html files
through the command prompt to a chm. We weren't able to find any way to
convert the files to a chm through the command prompt using RoboHelp.

I've set up loads of groups for each specific module which builds a good
table of contents.

Hope this helps. If you have any further questions, let me know.

Thanks,
Katherine

<katherinet -at- csl -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


_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com


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

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

Previous by Author: (summary) c++ api help: tips & resources
Next by Author: True Technical Writer
Previous by Thread: (summary) c++ api help: tips & resources
Next by Thread: Re: Creating Inch & Metric Tutorials

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads