Re: documentation and such

[Paul E Johnson]

"Marcus G. Daniels" wrote:
> 
> >>>>> "PJ" == Paul E Johnson <address@hidden> writes:
> 
> PJ> I need to start doing some better documentation, and I want to
> PJ> make notes inside source code and have them pop out in some nice
> PJ> way.
> 
> Do you mean to mark up source code for presentation of the source code
> or to mark it up for separate documentation?

Thanks for your feedback.  I think I want to markup in the source code
to have it presented as a separate document.  I can see from your
answers I've got to do some serious study (eg, what the hell is XSL?) if
I want to pull this off.

What gave me the idea is this program called doc++,
http://www.linuxsupportline.com/~doc++, that I saw on freshmeat.  It is
for c++, so it doesn't help me much in making docs for an objective-c
program. But here is how it works.  Whenever you want to add a paragraph
to your documentation about a method or such,  you just put it in the
header file with three slashes:
 
/// Here is a comment about this method

Then you run a program that grabs those things and some information it
gleans from your classes and makes a document about it.  IT lists all
the variables and methods, and whatever comments you put in.

I'm working with a team in Indiana and they need to have writups
explaining what all the methods do, what the variables are, and such.
HOwever, they have been preparing these writups in MS word, and it is
killing us to try to keep them up to date. I could generate that
information myself in the source code, but I'm simply unwilling to go
find  a machine with MS word and edit that document.

But I need something simple that I can use right away.  I am reading
about sed and awk and thinking of a simple way of just grabbing all
lines that start with /// and putting them into a file.  That would be
good enough for now.

-- 
Paul E. Johnson                       email: address@hidden
Dept. of Political Science            http://lark.cc.ukans.edu/~pauljohn
University of Kansas                  Office: (785) 864-9086
Lawrence, Kansas 66045                FAX: (785) 864-5700

                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.