July 2010 - Wine-Devel - list.winehq.org

Re: (Resent) Documentation - Reference to MSDN?

by Max TenEyck Woodbury

On 06/30/2010 03:13 PM, Alexandre Julliard wrote: > Erich Hoover<ehoover(a)mines.edu> writes: > >> Alright, well then I won't do it. Is the existing documentation going >> to be stripped at some point? It seems to me like we would benefit >> from more-detailed function descriptions in the auto-generated API >> documentation. I think it would save a lot of time for new developers >> to get their feet wet if they were able to see directly in the source >> what the different functions are supposed to do (as best as we know) >> and exactly what applications will trigger known edge cases (or if >> there's a test for a given situation). > > That's what the source code and test cases are for. If you rely on the > function documentation you are in trouble anyway, nobody bothers to > update it when new behaviors are discovered. > > If you really want to write good API documentation, as opposed to the > current useless one-sentence-per-parameter description, you'd need > probably a text 10 times the size of the source code for each > function. That can't go in the source files. > So, would it be OK with you to extract the current documentation and put it in the wiki where it can be more easily maintained? Wikis are supposed to be good for exactly that kind of thing. Once the wiki is populated with the initial information from the source code, the source code could then be cleaned up by having links to the wiki in place of the current cruft. Erich Hover's tree structure sounds like the right way to go. Formatting guidelines and templates to tag the article contents so the information can be easily extracted will be needed, but that belongs on the wiki, although issues should be discussed and decided on this mailing list.

July 1, 2010

Re: (Resent) Documentation - Reference to MSDN?

by Dmitry Timoshkov

Max TenEyck Woodbury <max(a)mtew.isa-geek.net> wrote: > I created the top page as a table and populated it with all the > directory entries in the 'dll' directory. Somebody immediately deleted > it. WTF? Creating a MSDN clone does not belong to the Wine project. -- Dmitry.

July 1, 2010

Re: (Resent) Documentation - Reference to MSDN?

by Max TenEyck Woodbury

On 06/30/2010 03:43 PM, Erich Hoover wrote: > On Wed, Jun 30, 2010 at 1:36 PM, James Mckenzie > <jjmckenzie51(a)earthlink.net> wrote: >> ... >> How about some place on the Wiki along with an implementation status. That way we can also annotate items that are missing in MSDN (I just re-stumbled across something in my latest Richedit tests) as well. This would help greatly in our progress towards current and future implementations of the Windows API. >> >> And I agree, adding all of this to the source would make it unwieldy. >> > > So something like "http://wiki.winehq.org/WineAPI/<DLL>/<Function>" ? > If that's acceptable I would not mind a system like that, especially > if the links of documented functions are provided in the source. > Documenting these things is a lot of work, so I'm not about to run off > and do all that work if no-one is ever going to take advantage of it. > > Erich Hoover > ehoover(a)mines.edu > > > I created the top page as a table and populated it with all the directory entries in the 'dll' directory. Somebody immediately deleted it. WTF?

July 1, 2010