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.
