Internally maintained end-to-end API documentation

[Gregory M. Turner]

On Saturday 13 December 2003 04:40 am, Joshua Walker wrote:
> 	There is one thing that really bugging the heck out
> of me.
> 	Most of the API documentation is possessed by MSDN.
> 	In my humble opinion, this is a very dangerous and
> volatile place to have it.
>
> 	I was once told that using the internet as a data
> resource is like watching The Library of Alexandria
> burn over and over again.

lol.  That's about right.  However, if you subscribe to MSDN Library, you can 
get snapshots of the Library on DVD.  They are pretty complete, do not create 
logs at Microsoft every time you research any small thing, and they do not 
disappear at the whim or accident of Microsoft.

Better still: I find that most info I need to develop wine is part of the 
Platform SDK;  this is a freely downloadable subset of the Library from 
Microsoft (if you consider a click-through EULA "free").

> 	I think it's about time to take the various Windows
> APIs and place them onto a fishbowl for safe keeping.

Wine has its own internal (in-source) documentation which is robotically put 
somewhere on the web.  Some if it is good, some of it sucks... you are 
welcome and encouraged to contribute.

> 	 Having lurked here for as long as I have, I have
> found two constants about announcing projects on
> wine-devel that I'd like to share.
> 	1)  In order to have Alexandre change direction, you
> better have a very good reason.

that's a good thing.

> 	2) Many ideas have been announced here with no real
> clear goal or steps of execution. They soon die of
> atrophy shortly after.

so is that :)  Wine requires lots of brainstorming and tossing of ideas back 
and forth.  Also, unpaid volunteers are probably less likely to follow 
through sometimes.  For example, I'm guilty of this across several axes.  
Also, some projects, like the Internet Exploder replacement for example, are 
simply put on the backburner for technical or project-scope reasons, although 
they really are not discarded, and will eventually arrive.

> 	As for myself, I'm thinking to taking up the mantle
> for documenting the Windows API, or at least setting
> up public facilties for myself and others to use. The
> problem I have is how about will it be documented?

Good idea.

> 	First goal is to figure out where on earth to *put*
> the documentation.. I'm thinking of some kind of
> universal data holder where API information can
> aggregated, parsed, and rendered to one's choosing. As
> I shook my magic hate-ball I asked, "What do you think
> about storing the API data in some kind of
> XMLish-thingy format?"
> 	All signs pointed to yes.
> 	This is quite tragic as my knowledge of XML is really
> weak. As far as I know, it's that HTML superset, isn't
> it?

For a start, just follow the conventions you see in the wine sources already.  
They will be picked up by the robot and put on-line AFAIK.

> 	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. The SQL idea is
> nice because I can write the front end to spit out
> what I have in any data format I can dream of,
> including XML. It also allows people to come to my
> website, pop in an API function that wan't there, and
> move on with their lives. That seems plausible.

I think this is overkill.  In-source doc's are good enough for now, and if we 
eventually need something more sophisticated, one of the perl hackers around 
here will have a conversion plan.

> 	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. See "man
> fork" for example. We will also need kind of a DLL
> overview, (man stdio?). What about something a little
> more UML compatible.

Again, there are existing conventions you can follow.  They are quite simple 
and easy to implement, and there are abundant examples in the source.

Good luck!  I welcome your enthusiasm and look forward to your patches.  One 
word of advice: I am not a big fan of legal nonsense, but please bear in mind 
that the Microsoft documentation is copyrighted.  A good way to avoid 
infringement is to document the functionality you see implemented in the wine 
sources, using MSDN only for proofreading purposes, or not at all.

-- 
gmt

"It is to be the assent and ratification of the several States,
derived from the supreme authority in each State, the authority
of the people themselves.  The act, therefore, establishing the
Constitution, will not be a NATIONAL, but a FEDERAL act." --James
Madison, Federalist No. 39