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?
On 06/30/2010 09:22 AM, Max TenEyck Woodbury wrote:
1) 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.
2) Would enumerating coded values and flags be allowed? That's what headers are for.
3) 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:
1) 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.
2) 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....
3) 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
participants (3)
-
James McKenzie -
Max TenEyck Woodbury -
Vitaliy Margolen