TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Re: Software that retrieves developer comments from code
Subject:Re: Software that retrieves developer comments from code From:Sandy Harris <pashley -at- storm -dot- ca> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 28 Mar 2002 15:32:47 -0500
Cara O Sullivan wrote:
> Is there a software package out there that can retrieve developer comments
> from code and does it easily and cleanly? Our developers provide in-house
> customizions of Peoplesoft (previously known as Vantive) and IFS vendor
> software.
>
> (Checked the archives and couldn't find anything on this topic.)
There are a lot of papers and some tools around for "literate
programming".
A web search on that phrase should turn up far more than you need. e.g. http://www.literateprogramming.com/
The phrase was originally the title of an essay of Knuth's. http://www-cs-faculty.stanford.edu/~knuth/lp.html
He had tools to build both docs and compilable modules from a common
source
file. I think his were for Pascal and TeX. There have been several
variants
produced since.
There's a current project to document the Linux kernel in this way. They
have tools that extract specially formatted comments plus some critical
data like function declarations, and format the result using the DocBook
(www.docbook.org) DTD. I'm not sure if they currently use SGML or XML.
Anyway, from there standard Linux tools (see www.linuxdoc.org) will get
you to HTML, PDF, ...
For a quick and dirty solution, just adopt some easily searched comment
convention. For example, in C, use:
/*
* This is a comment I want extracted
* It can be spread over as many lines as I like
*/
Then you can extract these with something like:
grep '^.\*' *.h *.c
This finds all lines with '*' in the second position.
(^ is start-of-line, '.' is any character)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at 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.
