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?
On 06/30/2010 09:22 AM, Max TenEyck Woodbury wrote:
- Would including the URL of the MSDN article be useful/a good idea?
No. Microsoft in all these years haven't figured out how to create permanent links. All, and I really mean it _ALL_ URLS on MSDN had changed at least once a year.
- Would enumerating coded values and flags be allowed?
That's what headers are for.
- Where should data structures be documented?
On MSDN. Wine is an implementation of API not the spec.
Vitaliy.
Vitaliy Margolen wrote:
On 06/30/2010 09:22 AM, Max TenEyck Woodbury wrote:
- Would including the URL of the MSDN article be useful/a good idea?
No. Microsoft in all these years haven't figured out how to create permanent links. All, and I really mean it _ALL_ URLS on MSDN had changed at least once a year.
They have learned well from IBM. I have links that I use at work that change on an almost weekly basis.
- Would enumerating coded values and flags be allowed?
That's what headers are for.
Correct. However, if a flag is used in more than one place, it would be 'nice' to annotate that the flag/enumeration does exist. Saves embarrassing and unnecessary patch submissions....
- Where should data structures be documented?
On MSDN. Wine is an implementation of API not the spec.
I agree. The functions and their calls/results are what we are interested in. We don't care how M$ got there, we are on a different path.
James McKenzie
-
James McKenzie -
Max TenEyck Woodbury -
Vitaliy Margolen