Internally maintained end-to-end API documentation

[Joshua Walker]

--- "Brian Vincent (C)" <VincentB at coppercolorado.com>
wrote:
> 

<snip>

> 
> >       Stepping back a bit, I started thinking of
> tossing an 
> > SQL database on one of my machines and writing
> some 
> > kind of dynamic HTML front end for it. 
> 
> I wouldn't.  Wine has lots of tools in use for
> building and 
> searching documentation, not the least of which is
> "grep".  

You know, funny things happen when you actully read
the manual (^_^)

I'm up to speed on how the API is documented in the
code now. I'm going to start there. I was going to
pull down the latest CVS and start working on it when
I thought it might be a good idea to clean out the old
cruft in my /opt dir.

root# rm -rf /opt/*

And so /opt/gnome and /opt/kde are now history. (Oops!
Who the heck put *Those* in there! Can someone tell me
why on earth it wasn't in /usr/X11/* like the rest of
X apps in the known universe? Better yet, why is vim
linked against GTK? Isn't that suppoed to be able to
run when they system is smashed?)

As I am wihout a desktop envionment, I'm forced to use
the windows "lab box" as I scratch my head and figure
out how to get Gnome 2 on my system. (I was running
1.4, I needed the upgrade anyway) This puts a bit of a
kabosh on the documentation process. I was going to
throw around a few formatting ideas (Of course, while
not breaking the current formatting rules) I can be a
bit verbose at times and wanted to bounce some ideas
off of the group at large.

> >       The second hurtle is what to put as the
> actual 
> > fields. I'm really only used to seeing function 
> > rendered an a "Unix man style" format. Name,
> synopsis, 
> > description, return value, errors, bugs. 
> 
> I actually really like this idea.  The standard C
> library is 
> nicely documented in man pages, why shouldn't Win32
> be the same 
> way?  I don't think we need another document format
> or repository 
> (Side note, is it just me, or is the GNU texinfo
> format the 
> stupidest form of documentation ever invented..) 
> The important 
> thing is, keep the documentation in a format that is
> easily 
> modifiable by developers.  Since most have a copy of
> CVS laying 
> around that probably means keeping docs in a text
> format somewhere 
> in the documentation/ directory. 

I was going to see what I can do to insert this into
the code without creating these HUGE headers.
Depending on the cosmetics however, it might me a good
thing.

> The scope of this project is huge.  In some ways
> you're trying 
> to recreate MSDN, and as Greg pointed out that
> documentation 
> lives on real media in the hands of thousands of
> people.  Yes, 
> it might be nice to replicate that but copyright
> issues are 
> something you'll need to be aware of.  If you
> rewrite all of 
> it by hand you definitely won't infringe on
> copyrights, but is 
> there an easier way put it together?  Something
> tells me there's 
> already some resources out there that could be used
> as a foundation. 

I was only going to use MSDN as a simple cross-check.
I enjoy writing with my own ten fingers. Cut and paste
is out of the question.
 
> Also, be sure to read the "Terms of Use" link at the
> bottom of 
> msdn.microsoft.com.  It may as well just say "You
> can only read 
> our web pages." 

Typical (^_^)
 
> A quick search on Google alludes to people writing
> man pages for 
> Win32.  This was on a NetBSD mailing list: 
> 

I'll have to research this when Naru's running at 100%
again. If it's GPLed, I could expand on that. 

Th only real issue I have is that some API fuctions
can be pretty complex in thier execution. This could
make for rather large function headers in the code.
That's why, then things are normal again, I'll bouce
some code snippits to the group before I kick a full
blown patch to be accepted.

-Joshua

P.S. I'm on a really crapy mail client. The spell
checker is a bit fruity and has been known to eat my
corrispondance in the past. Please ignore the mild
dislexia. I like to think of it as a gift that I can
read backwards quicker than forewards.

I solved that problem by majoring in Japanese (^_^)