The WineAPI wiki.

Francois Gouget fgouget at free.fr
Fri Aug 6 04:44:55 CDT 2010


On Thu, 5 Aug 2010, Max TenEyck Woodbury wrote:
[...]
> > Here's roughly what I have in mind:
> > 
> >     1. Win32 API
> >        1. Overview
> >        2. acledit API
> >           1. Overview
> >           2. Functions
> >              1. Func1
> >              2. Func2
> >              ...
> >           3. Interfaces
> >              1. Interface 1
> >                 1. Method1
> >                 2. Method2
> >                 ...
> >              2. Interface 2
> >                 1. Method1
> >                 2. Method2
> >                 ...
> >           4. Datastructures
> >              1. Struct1
> >              2. Struct2
> >              3. Enum1
> >              ...
> >        3. aclui API
> >        ...
> >     2. Standard Windows tools
> >        1. attrib command line options
> >        2. cacls command line options
> >        ...
> >     3. General platform-specific notes
> >        1. Windows 9x
> >           Talks about interaction with DOS, etc.
> >        2. Windows 95
> >           More Win 9x specific general notes
> >        3. Windows NT and greater
> >           Kernel stuff
> >        4. Wine
> >           1. Wine architecture documentation
> >           2. Wine-specific dlls
> >           3. Wine-specific tools like winebuild, winemenubuilder, etc)
> >        5. Mingw
> >           Stuff about Mingw, etc.
> >        6. ReactOS
> >           Stuff about ReactOS, etc.
> > 
> Ah! That is where the misunderstanding is. You are thinking of this as
> a *document*, a single coherent document.

I am not thinking of this as a single document. Each of the above line 
would be a separate wiki page.

[...]
> Those names are what the scripts maintain.

I'm not sure what there is to maintain.

> The pages will also contain sub-pages. Those sub-pages are where the 
> user-editable content are stored.

Do you mean that the documentation for an API like CreateFile() would be 
a collection of pages? That seems counterproductive to me.


> There is also technical content. Such things as the names of the entry 
> points, the return type, the number of parameters and their types.
> That information really should not be subject to debate. It is 
> determined by the implementation.

Well, yes. That's what Func1, Func2 are above. And on their pages you 
would get the signature, general documentation of the function, 
description of what each parameter is for, links to the pages describing 
the types of the parameters if they're complex, what the function 
returns, finer points about how the function behaves in corner cases if 
appropriate, and platform-specific details about how it behaves.


> That might be something the scripts can maintain, however I will leave 
> that maintenance until later.

However while it would be easy for scripts to create a skeleton page, 
once the page exists and has been editied they may have a hard time 
changing stuff like correcting the type of an output parameter.

But I guess that's why you want to have sub pages I guess. Though I 
really would not want to have to go through multiple pages for each of 
the documentation aspects I mentioned above.


> I suspect that the meta-information will in fact have to be duplicated.
> It can be different for the different projects. For example Wine is
> similar to the Microsoft stuff at the file level. They each have DLLs
> with corresponding names. On the other hand, WinGW consists of a single
> DLL, if I understand its structure correctly.

My mingw-runtime package has a lot of separate 'dlls': libaclui.a, 
libadvapi32.a, libgdi32.a, etc. Besides, how does that matter? 
CreateFile() is a kernel32 fnuction, no matter what, and the 
documentation should reflect that.


[...]
> There is complication here no matter how it is done. There is simply
> too much stuff to keep it really simple. Category markers should be
> used extensively. Redirection links will be needed to provide views
> from different perspectives without having to actually replicate
> articles.

That's one of the things I don't like in msdn. Want do know what's the 
API provided by a given dll? Good luck with that because they seem bent 
on hiding that kind of information.

I think we should really have per-dll documentation and the general 
articles about 'how to do sound', 'what COM is' should be in a separate 
section. Otherwise your documentation of CoCreateInstance() is going to 
keep moving from OLE to COM to DCOM and to whatever today's fashionable 
marketing term is.


-- 
Francois Gouget <fgouget at free.fr>              http://fgouget.free.fr/
                          "Utilisateur" (nom commun) :
        Mot utilisé par les informaticiens en lieu et place d'"idiot".


More information about the wine-devel mailing list