Re: (Resent) Documentation - Reference to MSDN?
James McKenzie jjmckenzi...@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.
Re: (Resent) Documentation - Reference to MSDN?
On Fri, Jul 2, 2010 at 3:51 AM, Dmitry Timoshkov dmi...@codeweavers.com wrote: James McKenzie jjmckenzi...@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 ehoo...@mines.edu
Re: (Resent) Documentation - Reference to MSDN?
On 06/30/2010 03:13 PM, Alexandre Julliard wrote: Erich Hooverehoo...@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.
Re: (Resent) Documentation - Reference to MSDN?
Max TenEyck Woodbury m...@mtew.isa-geek.net writes: 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. That's fine, but please don't hijack the Wine wiki for this, start a separate one. -- Alexandre Julliard julli...@winehq.org
Re: (Resent) Documentation - Reference to MSDN?
On Thu, Jul 1, 2010 at 7:56 AM, Alexandre Julliard julli...@winehq.org wrote: Max TenEyck Woodbury m...@mtew.isa-geek.net writes: 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. That's fine, but please don't hijack the Wine wiki for this, start a separate one. If we mock up an example, and it is deemed acceptable, would we be permitted to make patches replacing the in-code documentation with the URL for the appropriate function? The idea here would be to accomplish several goals: 1) Give new Wine developers somewhere to look for documentation to help them get started 2) Give current Wine developers investigating something outside of their expertise some information to help familiarize them with another area of the API 3) Provide unchanging URLs that can legitimately be used in the source code without fear of them changing every week (or being lost forever in the case of some older functions) 4) Document the ever-growing list of unexpected behaviors that MSDN will never tell you about Obviously this is a big task and it's not something that is going to happen overnight, but I think that such a wiki could provide a useful service to the Wine community. My primary concern here is participation, since if there's little or no participation it will never grow to the magnitude that's necessary for it to be a helpful resource. So, I guess I'm saying that if there's at least some chance of embedding URLs in the source that will direct people to this documentation then I'd feel much more comfortable investing my free time in setting something up. Erich Hoover ehoo...@mines.edu
Re: (Resent) Documentation - Reference to MSDN?
Erich Hoover ehoo...@mines.edu writes: Obviously this is a big task and it's not something that is going to happen overnight, but I think that such a wiki could provide a useful service to the Wine community. My primary concern here is participation, since if there's little or no participation it will never grow to the magnitude that's necessary for it to be a helpful resource. So, I guess I'm saying that if there's at least some chance of embedding URLs in the source that will direct people to this documentation then I'd feel much more comfortable investing my free time in setting something up. We can have pointers on the website or the README, and we can probably find a way to have doc links in the lxref source browser. We certainly don't want a URL in front of each function in the source, it will be a major pain when they change (and trust me, they will). Just make sure that your pages are properly indexed by Google. -- Alexandre Julliard julli...@winehq.org
Re: (Resent) Documentation - Reference to MSDN?
My primary concern here is participation Count me in! I think it would be a great way to learn the wine/windows internals. Peter
Re: (Resent) Documentation - Reference to MSDN?
On 07/01/2010 04:34 AM, Dmitry Timoshkov wrote: Max TenEyck Woodburym...@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
Re: (Resent) Documentation - Reference to MSDN?
On Thu, Jul 1, 2010 at 8:06 PM, Erich Hoover ehoo...@mines.edu wrote: 3) Provide unchanging URLs that can legitimately be used in the source code without fear of them changing every week (or being lost forever in the case of some older functions) 4) Document the ever-growing list of unexpected behaviors that MSDN will never tell you about Why would we want to help Micro$oft with that? How did they ever contribute to the open source community to deserve that? As I see it, Wine's primary goal is to aid in the migration from Windows, a closed platform, to an open platform like Linux. There is enough to do already (kernel, system dlls, many many libraries, installer, directx, command line tools, various programs and tools, testing infrastructure, translations, etc), if we spread ourselves too thin we won't get anywhere with anything. Imho there are very few cases in which better documentation would benefit our cause, but I'm pretty sure that devoting that time to writing wine code instead of winapi documentation would have a much greater impact. Octavian PS: there are other resources except MSDN; for example, osronline.com has very good documentation for windows driver developers, including some undocumented APIs.
Re: (Resent) Documentation - Reference to MSDN?
On Fri, Jul 2, 2010 at 7:35 AM, Octavian Voicu octavian.vo...@gmail.com wrote: PS: there are other resources except MSDN; for example, osronline.com has very good documentation for windows driver developers, including some undocumented APIs. I don't know if this is worth mentioning or not, Geoff Chappell maintains a website with some in depth information covering Windows internals, granted the methods used to discover the information may not be in line with what a Wine contributor is allowed to do, but in the same spirit of quality information he has proposed an initiative producing an Opened Windows Library (OWL) as an alternative to Microsoft’s MSDN Library. Maybe this could be what you're looking for. http://geoffchappell.com/viewer.htm?doc=index.htm http://www.soared.org/ http://www.soared.org/plan/index.htm http://www.soared.org/plan/faq.htm PS. The idea of publishing this information to a wiki seems a little ad-hoc, wouldn't it be better to put things under a dvcs (like git) and then publish based on that?
Re: (Resent) Documentation - Reference to MSDN?
Dmitry Timoshkov wrote: Max TenEyck Woodbury m...@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
(Resent) Documentation - Reference to MSDN?
I've been reading the Wine code and noticed that some of the external interfaces are practically undocumented. I did a web search on some of the names and found descriptions in MSDN. I realize that copying the information from MSDN directly into the code is a poor idea (like copyright violation) so I have a couple of questions: 1) Would including the URL of the MSDN article be useful/a good idea? 2) Would enumerating coded values and flags be allowed? 3) Where should data structures be documented?
Re: (Resent) Documentation - Reference to MSDN?
Hi Max, 1) Would including the URL of the MSDN article be useful/a good idea? No. MSDN is in the habit of changing its URLs all too frequently. A more general response: I'm not sure that a lot of documentation patches will be accepted. MSDN has to be considered the definitive resource for the Windows API. It's often incorrect, of course, and our regression tests aim to ameliorate the inaccuracy, but we probably have enough work implementing the Windows API without taking on the task of documenting it too. --Juan
Re: (Resent) Documentation - Reference to MSDN?
Am 30.06.2010 19:25, schrieb Max TenEyck Woodbury: I've been reading the Wine code and noticed that some of the external interfaces are practically undocumented. I did a web search on some of the names and found descriptions in MSDN. I realize that copying the information from MSDN directly into the code is a poor idea (like copyright violation) so I have a couple of questions: 1) Would including the URL of the MSDN article be useful/a good idea? Might be a bad idea as such URL may be dead in 12 Month or so, but it is not forbidden. 2) Would enumerating coded values and flags be allowed? That is the best solution i think. -- Best Regards, André Hentschel
Re: (Resent) Documentation - Reference to MSDN?
No. MSDN is in the habit of changing its URLs all too frequently. For what it's worth, while MSDN seems to like changing its URLs a lot, it does seem to be quite good at maintaining forwarders for the old URLs - most API documentation URLs I've randomly found from 5 years ago still work, for instance. But I agree that it's probably not worth including them in Wine's documentation. -- Owen Rudge http://www.owenrudge.net/
Re: (Resent) Documentation - Reference to MSDN?
On Wed, Jun 30, 2010 at 11:44 AM, Juan Lang juan.l...@gmail.com wrote: ... A more general response: I'm not sure that a lot of documentation patches will be accepted. MSDN has to be considered the definitive resource for the Windows API. It's often incorrect, of course, and our regression tests aim to ameliorate the inaccuracy, but we probably have enough work implementing the Windows API without taking on the task of documenting it too. --Juan I was looking into this a while ago and you can add documentation to the Wine API by properly formatting it in your patches, for example: http://source.winehq.org/WineAPI/CreateIcon.html is generated from the code here: http://source.winehq.org/source/dlls/user32/cursoricon.c#L1473 Personally, I think that it would be really good to do a better job of documenting the API functions (particularly edge cases). I'm currently very busy with work, but if Alexandre is ok with documentation-only patches then this is something I'm tempted to jump on (in the areas where I have sufficient familiarity) when I have some more free time. Erich Hoover ehoo...@mines.edu
Re: (Resent) Documentation - Reference to MSDN?
Juan Lang: grin Of course one of the reasons to add documentation is precisely because the information on MSDN is less than perfect. Having a good interface definition makes things easier. I'm still in the process of learning how to submit patches. These would be low risk but useful changes so they make good test material. Juan Lang, André Hentschel, Owen Rudge: So, from what Owen said, having a URL can be helpful, but should not be the total documentation. A date as part of the reference probably would be enough warning that things change. Alexandre: Would you mind getting documentation update patches during the code freeze?
Re: (Resent) Documentation - Reference to MSDN?
Erich Hoover ehoo...@mines.edu writes: Personally, I think that it would be really good to do a better job of documenting the API functions (particularly edge cases). I'm currently very busy with work, but if Alexandre is ok with documentation-only patches then this is something I'm tempted to jump on (in the areas where I have sufficient familiarity) when I have some more free time. I'm not OK with it. If you want to start a project to document the Windows API, go ahead, but don't put that in the Wine source, that's not where it belongs. -- Alexandre Julliard julli...@winehq.org
Re: (Resent) Documentation - Reference to MSDN?
On Wed, Jun 30, 2010 at 12:44 PM, Alexandre Julliard julli...@winehq.org wrote: Erich Hoover ehoo...@mines.edu writes: Personally, I think that it would be really good to do a better job of documenting the API functions (particularly edge cases). I'm currently very busy with work, but if Alexandre is ok with documentation-only patches then this is something I'm tempted to jump on (in the areas where I have sufficient familiarity) when I have some more free time. I'm not OK with it. If you want to start a project to document the Windows API, go ahead, but don't put that in the Wine source, that's not where it belongs. 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). Erich Hoover ehoo...@mines.edu
Re: (Resent) Documentation - Reference to MSDN?
Erich Hoover ehoo...@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. -- Alexandre Julliard julli...@winehq.org
Re: (Resent) Documentation - Reference to MSDN?
On 06/30/2010 03:13 PM, Alexandre Julliard wrote: Erich Hooverehoo...@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. That documentation has to be stored somewhere. Where?
Re: (Resent) Documentation - Reference to MSDN?
Alexandre Julliard julli...@winehq.org wrote: Erich Hoover ehoo...@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
Re: (Resent) Documentation - Reference to MSDN?
On Wed, Jun 30, 2010 at 1:36 PM, James Mckenzie jjmckenzi...@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 ehoo...@mines.edu
Re: (Resent) Documentation - Reference to MSDN?
Erich Hoover ehoo...@mines.edu wrote: Sent: Jun 30, 2010 12:43 PM To: James Mckenzie jjmckenzi...@earthlink.net Cc: Alexandre Julliard julli...@winehq.org, Max TenEyck Woodbury m...@mtew.isa-geek.net, wine-devel@winehq.org Subject: Re: (Resent) Documentation - Reference to MSDN? On Wed, Jun 30, 2010 at 1:36 PM, James Mckenzie jjmckenzi...@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. +1 Acceptable variables should be listed in an order other than the one on MSDN. We don't want a direct copy, but rather OUR findings using the old 'black box' method. James McKenzie
Re: (Resent) Documentation - Reference to MSDN?
On 06/30/2010 03:43 PM, Erich Hoover wrote: On Wed, Jun 30, 2010 at 1:36 PM, James Mckenzie jjmckenzi...@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 ehoo...@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?
Re: (Resent) Documentation - Reference to MSDN?
Max TenEyck Woodbury m...@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.
