Internally maintained end-to-end API documentation - wine-devel

13 Dec 2003


      Hello all,
    I have been a lurker, going on now a good part of
three years. I have some ideas I wish to cast to the
table. I am a writer, not a programmer by craft. This
hindrance aside, I have kicked around my fair share of
C code. I have also been known to throw gooey
splatterings of VMS report data  into Postgres, and
somehow rationalize it into something coherent on the
other side for pay.
    After reading Wine Weekly News Issue #200, (Congrats
by the way), I stumbled across the Wine Status Pages.
I particularly like how everything is grouped by major
components. With a quick glance at a color-coded
graph, one can see how well something has been
implemented.
    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. Having attempted to be a
code developer for Microsoft products in the past, I
know how quick MSDN can be when it comes to pulling
the data out from under your feet. I also know what
it's like to go hunting for some bizarre
functionality, only to have MSDN look at you back with
nothing but a blank stare on it's face. Sometimes it's
the "little things" like the deep inner workings of
interprocess communication. Better yet, why on earth
is my stack is being messed with after a function
call.
    I think it's about time to take the various Windows
APIs and place them onto a fishbowl for safe keeping.
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.
    2) Many ideas have been announced here with no real
clear goal or steps of execution. They soon die of
atrophy shortly after.
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?
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?
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.
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.
Anyone have any ideas? Admittedly this is where my
coherence of the project ends. There might be someone
out there a little more apt at content than I am.
Let me close with a story;
    When I was 12 my mother bought a brand new washing
machine. My mother gave me the old one and a set of
wrenches, and then proceeded to tell me to go nuts.
    In the span of five hours there was washing machine
all over our front lawn. I learned more about about
washing machines at the age of 12 by tearing that
thing apart more than most adults know now.
It's kinda what I want to do with Windows.
-Joshua