Internally maintained end-to-end API documentation
Gregory M. Turner
gmturner007 at ameritech.net
Sat Dec 13 10:16:48 CST 2003
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?
> 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
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.
"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
More information about the wine-devel