Re: Software that retrieves developer comments from code

Subject: Re: Software that retrieves developer comments from code
From: Chris Gooch <chris -dot- gooch -at- lightworkdesign -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 2 Apr 2002 10:17:41 +0100


Cara -

Sandy's link to "literate programming" stuff is good background reading.
If the code you are documenting is written in C++ then you can get
some excellent results using Perceps:
http://starship.python.net/crew/tbryan/PERCEPS/

Which is free software. It produces good documentation of all the
classes and functions etc., as hierarchical html pages. If you wish,
you can add source code comments in a set format and they will
be extracted and placed in the right points in the html pages. It works
for us. Can't comment in Doxygen as not used it.

I wouldn't write your own scripts to strip comments unless you
are looking for a project to do -- such tools have been written before,
and are available for free.

I'm pretty certain we had a discussion on this topic last year,
not sure what the thread name would have been though
as I think we digressed from another subject... one comment
I made at that time though was to be sure that the techwriter
and developer teams know who can edit what --- and that,
unless your source code is the cleanest in the world, you
might want to check some of the comments that developers
write before showing them to customers... I once found the
following comments in live source code (not at my present
employer I hasten to add!) :-)

% This used to be wrong but didn't work so now I've fixed
% it and it's right, but it doesn't work...

and

% This code has more bugs than a tramps overcoat...


Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
chris -dot- gooch -at- lightworkdesign -dot- com www.lightworkdesign.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
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: Big Word Docs?
Next by Author: RE: Re: Software that retrieves developer comments from code
Previous by Thread: RE: Software that retrieves developer comments from code
Next by Thread: RE: Re: Software that retrieves developer comments from code


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


Sponsored Ads