(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?
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
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/
On Wed, Jun 30, 2010 at 11:44 AM, Juan Lang <juan.lang(a)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 ehoover(a)mines.edu
Erich Hoover <ehoover(a)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 julliard(a)winehq.org
On Wed, Jun 30, 2010 at 12:44 PM, Alexandre Julliard <julliard(a)winehq.org> wrote:
Erich Hoover <ehoover(a)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 ehoover(a)mines.edu
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. -- Alexandre Julliard julliard(a)winehq.org
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.
That documentation has to be stored somewhere. Where?
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.
Max TenEyck Woodbury <max(a)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 julliard(a)winehq.org
On Thu, Jul 1, 2010 at 7:56 AM, Alexandre Julliard <julliard(a)winehq.org> wrote:
Max TenEyck Woodbury <max(a)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 ehoover(a)mines.edu
Erich Hoover <ehoover(a)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 julliard(a)winehq.org
Am 01.07.2010 19:26, schrieb Peter Davies:
My primary concern here is participation
I think http://wiki.jswindle.com would also be a good place if he would cooperate... BTW: we should slowly come to an end with that discussion on wine-devel IMO -- Best Regards, André Hentschel
On Thu, Jul 1, 2010 at 8:06 PM, Erich Hoover <ehoover(a)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.
On Fri, Jul 2, 2010 at 7:35 AM, Octavian Voicu <octavian.voicu(a)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?
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
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?
participants (9)
-
Alexandre Julliard -
André Hentschel -
Erich Hoover -
Jeff Zaroyko -
Juan Lang -
Max TenEyck Woodbury -
Octavian Voicu -
Owen Rudge -
Peter Davies