30 Jun
2010
30 Jun
'10
5:25 p.m.
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?
30 Jun
30 Jun
5:44 p.m.
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
5:54 p.m.
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/
6:10 p.m.
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
6:44 p.m.
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
6:54 p.m.
On Wed, Jun 30, 2010 at 12:44 PM, 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).
Erich Hoover
ehoover(a)mines.edu
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.
7:13 p.m.
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
7:21 p.m.
On 06/30/2010 03:13 PM, Alexandre Julliard wrote:
Erich Hoover<ehoover(a)mines.edu> writes:
That documentation has to be stored somewhere. Where?
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.
1 Jul
1 Jul
1:14 p.m.
On 06/30/2010 03:13 PM, Alexandre Julliard wrote:
Erich Hoover<ehoover(a)mines.edu> 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.
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.
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.
1:56 p.m.
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
5:06 p.m.
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:
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
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.
5:26 p.m.
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
5:32 p.m.
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
9:35 p.m.
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.
11:39 p.m.
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?
30 Jun
30 Jun
5:45 p.m.
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
6:43 p.m.
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?
5071
days inactive
5072
days old
17 comments
9 participants
participants (9)
-
Alexandre Julliard -
André Hentschel -
Erich Hoover -
Jeff Zaroyko -
Juan Lang -
Max TenEyck Woodbury -
Octavian Voicu -
Owen Rudge -
Peter Davies