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.
Subject:Documentation from uncommented C Code From:Susan Brown <sbrown -at- JSCSYS -dot- COM> Date:Fri, 14 Feb 1997 13:01:21 -0500
This post comes under the heading 'Life is hard: then you die.'
Due to development overruns, I have been placed in the position of
starting work on the system maintenance manuals for a fairly complex system
without any developer help (initially).
I have been handed volumes of (mostly) uncommented C code. (I have
never programmed in C, or studied it in any depth, so my knowledge is
basically what I picked up in general about programming when I did my
degree, plus perusing Kernighan and Ritchie).
Manually sifting through this has proved time ineffective. I located
a tool (The STX Software Exploration Tool) which is helping me with some of
what I need (functions/routines, and data structure definitions. It is
actually quite useful). However, the developers and client both want
itemized lists of the global variables in the system. I have been unable to
find a tool that will provide this.
1) Do any of you know of any C tools that will parse files
(including includes) for Global variable definitions and usage????
2) Any general tips on constructing technical/maintenance references
from uncommented code?
3) More generally, how often have you faced this, and how do
you cope with it?
"Begin at the beginning," the King said, very gravely, "and go on till you
come to the end: then stop."
- Lewis Carroll