Re: de facto documentation tool

Brian Moelk wrote:
Time2HELP has a concept of UnitDoc files, which are separate xml
files which it can synchronize against the structure of the units
they document.
This way, it is possible to have UnitDocs in different languages for
the same source code and build multiple help files (you have to
create one T2H project for each help file (language) you want)

That's a nice feature indeed. The question I have now is if it can
regenerate the method/property stubs without clobbering existing
documentation.

If you add new stuff to the source code, that will be added to the unitdoc
files on the next synchronization.
But if you delete stuff from your source code, it won't get deleted from the
unitdoc files (at least not if it has documentation in the unitdoc file).
This is because it is impossible to tell whether you have deleted something
instead of not simply moved something to a different unit or renamed it, and
then you obviously don't want your old documentation to get deleted. So the
synchronization is rather conservative.

IOW, how does it manage change over time. I would
hope that it would be fine...but you never know. ;)

We think it manages fine, but as mentioned you sometimes want to delete some
old stuff which don't have correspondance to source code items anymore. (You
aren't required to delete old stuff, as the source code defines what is
current, but...)
Basically you have to do some cleaning (and/or renaming) of stuff in unitdoc
files when you are refactoring your source code.


I believe Doc-O-Matic also has a concept of storing documentation in
external files, but I don't know the details.

I've heard the same regarding doc-o-matic. The main issue for me
with these higher end products is their price point, and for me since
application help is much more important than code help my money is
going to be spent on applications like Help and Manual, Help
Scribble, etc.

For most of us, application help is what we need to deliver to customers.
But even if you aren't a component vendor, source code help might help you
in your daily work as a software developer.
Earlier today I found the following statement in some blog:
"Understanding code is by far the activity at which professional developers
spend most of their time."
If this is true, a source code documentation tool might be a very good
investment if it can reduce the time you spend trying to understand your
in-house code.

Cheers,
Jarle


.

Relevant Pages

  • Re: de facto documentation tool
    ... unitdoc files (at least not if it has documentation in the unitdoc ... then you obviously don't want your old documentation to get deleted. ... synchronization is rather conservative. ... Code visualization tools can be nice too. ...
    (borland.public.delphi.non-technical)
  • Re: TeX and friends
    ... There is a core of a Unix OS in the foundations, ... which does of course mean that it's easy to write a nice integrated GUI ... but what about when you can't write any documentation at all ... the source code is ...
    (uk.people.support.depression)
  • Re: Doc-O-Matic 3.7 released - Source Documentation System
    ... > Doc-O-Matic 3.7 is the latest version of our Source Code Documentation ... > PDF, HTML Help, Help 2 and Windows Help. ... > Markus Spoettl, ...
    (microsoft.public.dotnet.languages.vb)
  • Re: PIC/Linux
    ... and some documentation, shell scripts, etc., but nothing that needs to be made. ... and got a complaint that it couldn't find simulavr. ... I decided it would be helpful to look at the source code for the ... cpio --extract to extract the contents of the cpio file. ...
    (sci.electronics.misc)
  • Re: Python style: exceptions vs. sys.exit()
    ... So what's wrong with using the source as documentation? ... But when it comes to nitty-gritty details, source code is the ... language you don't understand (e.g. Python built-ins are written in C, ... language you understand and not too complicated for you to grasp, ...
    (comp.lang.python)