RE: Source code documentation systems?

Subject: RE: Source code documentation systems?
From: "Geoff Lane" <geoff -at- gjctech -dot- co -dot- uk>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 24 Jan 2001 14:22:08 -0000

Geoff Hart wrote:
>
> Michael Collier reports <<... systems, marketed to developers, which
> typically claim to find objects and comments in source
> code (Java, C, C++), create some kind of documentation based
> on these and
> output to RTF, HTML, HTML help. >>
>
> Never worked with such a system, but it seems to me to be a
> classic example
> of the garbage in, garbage out rule: if the developers insert
> well-written,
> consistent, helpful comments, you'll get something you can at
> least build
> on. Anyone want to bet on whether that's reliably going to be
> the case? If
> nothing else, I imagine that such tools would be a great way
> for building
> functional specifications on the fly, and if you work for a
> company where
> such docs are never created, it might be worth your while to
> invest in one,
> purely in self defence.
---

In Feb 1999, I needed to document an API and sought a commercial tool for
this. Although I received some recommendations, the suggested applications
were not up to the task. Here's an extract from my summary of 12 Feb 1999:
---
Thanks to Geoff Hart, who suggested that the developer was the best tool for
the job<g>. To some extent, I've implemented his suggestion<bg>.

During my search, I discovered the following:
DocJet (http://www.tall-tree.com/) (C, C++, VB)
API2Help (Microsoft Visual Studio add-in) (C++)
AutoDuck (Microsoft) (VB)
DocumentVB (http://www.innovasys.co.uk/) (VB)
JavaDoc (http://www.javasoft.com/products/jdk/javadoc/index.html) (Java)
---

Hopefully these will suit your needs better than mine<g>. For my solution, I
wrote a (project-specific) Word application that scanned the source files to
extract specific comments. This still produces the in-house API
documentation and (thanks to a development manager who understands the need
for good docs) requires little rework for an external audience.

HTH,

Geoff Lane
Cornwall, UK
geoff -at- gjctech -dot- co -dot- uk


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by DigiPub Solutions Corp, producers of PDF 2001
Conference East, June 4-5, Baltimore/Washington D.C. area.
http://www.pdfconference.com or toll-free 877/278-2131.

---
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: RE: For Hardware TWs - a question
Next by Author: RE: TOOLS: w.p. conversion software
Previous by Thread: Source code documentation systems?
Next by Thread: Re: Source Code Documentation Systems?


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

Sponsored Ads


Sponsored Ads