30 Jun
2010
30 Jun
'10
7:36 p.m.
Alexandre Julliard <julliard(a)winehq.org> wrote:
Erich Hoover <ehoover(a)mines.edu> writes:
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
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.
30 Jun
30 Jun
7:43 p.m.
New subject: (Resent) Documentation - Reference to MSDN?
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
1 Jul
1 Jul
2:02 a.m.
New subject: (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
<jjmckenzie51(a)earthlink.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?
...
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
2:34 a.m.
New subject: (Resent) Documentation - Reference to MSDN?
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.
2:04 p.m.
New subject: (Resent) Documentation - Reference to MSDN?
On 07/01/2010 04:34 AM, Dmitry Timoshkov wrote:
Max TenEyck Woodbury<max(a)mtew.isa-geek.net>
wrote:
But maybe it should? MSDN is famous for being pretty good, but
incomplete, incorrect and changing URLs all the time.
// Jakob
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.
2 Jul
2 Jul
2:41 a.m.
New subject: (Resent) Documentation - Reference to MSDN?
Dmitry Timoshkov wrote:
Max TenEyck Woodbury <max(a)mtew.isa-geek.net>
wrote:
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
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.
9:51 a.m.
New subject: (Resent) Documentation - Reference to MSDN?
James McKenzie <jjmckenzie51(a)earthlink.net> wrote:
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.
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.
2:58 p.m.
New subject: (Resent) Documentation - Reference to MSDN?
On Fri, Jul 2, 2010 at 3:51 AM, Dmitry Timoshkov <dmitry(a)codeweavers.com> wrote:
James McKenzie <jjmckenzie51(a)earthlink.net>
wrote:
"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.
...
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. 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
5070
days inactive
5072
days old
7 comments
5 participants
participants (5)
-
Dmitry Timoshkov -
Erich Hoover -
Jakob Eriksson -
James Mckenzie -
Max TenEyck Woodbury