Re: (Resent) Documentation - Reference to MSDN?
Alexandre Julliard <julliard(a)winehq.org> 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.
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. James McKenzie
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
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?
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.
On 07/01/2010 04:34 AM, Dmitry Timoshkov wrote:
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.
But maybe it should? MSDN is famous for being pretty good, but incomplete, incorrect and changing URLs all the time. // Jakob
Dmitry Timoshkov wrote:
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: I think you completely miss what this is all about. We are NOT creating an MSDN 'clone'. Maybe a cleaned up duplicate of soared.org. We do need to annotate, in one location, the project's findings and code that is pending implementation that was acquired through research of existing resources and validation through blackbox testing. It is NOT our purpose to provide sample code or anything like it. That is what MSDN is there for. To assist Microsoft Developers working with Windows products to produce Windows programs. Not to assist or aid any others in the pursuit of a 'look alike' API that just happens to run on UNIXy operating systems. I agree with Alexandre, we don't need to hijack the wiki for Wine to do this. Maybe we do need another wiki site that is separate from but equal to the current wiki, but for Wine developers/hackers only and their efforts to improve upon current Wine project efforts. James McKenzie
James McKenzie <jjmckenzie51(a)earthlink.net> wrote:
Creating a MSDN clone does not belong to the Wine project.
I think you completely miss what this is all about. We are NOT creating an MSDN 'clone'. Maybe a cleaned up duplicate of soared.org. We do need to annotate, in one location, the project's findings and code that is pending implementation that was acquired through research of existing resources and validation through blackbox testing.
It is NOT our purpose to provide sample code or anything like it. That is what MSDN is there for. To assist Microsoft Developers working with Windows products to produce Windows programs. Not to assist or aid any others in the pursuit of a 'look alike' API that just happens to run on UNIXy operating systems.
I agree with Alexandre, we don't need to hijack the wiki for Wine to do this. Maybe we do need another wiki site that is separate from but equal to the current wiki, but for Wine developers/hackers only and their efforts to improve upon current Wine project efforts.
Who are those "we"? I personally don't need anything listed above. Quoting Alexandre's response: "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." -- Dmitry.
On Fri, Jul 2, 2010 at 3:51 AM, Dmitry Timoshkov <dmitry(a)codeweavers.com> wrote:
James McKenzie <jjmckenzie51(a)earthlink.net> wrote:
... It is NOT our purpose to provide sample code or anything like it. That is what MSDN is there for. To assist Microsoft Developers working with Windows products to produce Windows programs. Not to assist or aid any others in the pursuit of a 'look alike' API that just happens to run on UNIXy operating systems. ...
Who are those "we"? I personally don't need anything listed above.
"We" is whomever wants to help with this idea. Preferably, many people like you that are already intimately aware with the details of at least some of the API. This kind of resource would be most beneficial for those that are either just getting started contributing to Wine or those branching out to fix something outside of their area of expertise. I know that I've been spending a large fraction of my free time researching how Windows handles animated cursors, consolidating the links to all the resources and the tidbits of information I've found would likely save anyone else looking into the same problems a lot of time. I still don't know what GetCursorFrameInfo does, and I have a hunch that it might be useful in doing a proper animated cursor implementation.
Quoting Alexandre's response: "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."
I would argue that good documentation is just as important as source code and test cases. It can save a lot of time in introducing new people to the code, even if it is somewhat out of date. On projects I've been in charge of in the past my policy has always been that the documentation is in the code and generated by a script - that usually works as a pretty good eyesore to get developers to update it as they go. However, since that's off the table there are other methods for keeping documentation up to date. For example, a "Documentation Tracker" could be setup for the documentation folks to review new commits and see if they warrant an update to the documentation. Erich Hoover ehoover(a)mines.edu
participants (6)
-
Dmitry Timoshkov -
Erich Hoover -
Jakob Eriksson -
James McKenzie -
James Mckenzie
-
Max TenEyck Woodbury