As my previous efforts have probably informed you, I am interested in documentation. My initial efforts were _not_ on target and had missed the existing 'c2man.pl' tool. I am in the process of correcting my failure on that.
I've picked up Perl in the last couple weeks. An interesting language with lots of adopted features. It's been easy to learn, so I think I will _not_ need help with the language itself, but I will listen to any advice.
The c2man.pl code is extensive and sparsely commented. In order to understand what it does, I've made a transcription of it with a more compact style and lots more comments. I check the rewrite against the source code so there should not be any serious errors. There are also a number of what I believe to be defects in the original and places where my comments may be inappropriate or my style may be very objectionable. _This_ is what I need help with.
Would someone be willing to review my rewrite? If so, send me e-mail so I can arrange to get a copy of it to you.
P.S. to AJ et al.
There is a _lot_ of documentation embedded in the wine code, but it is hard to find at the moment. I'd like to see it indexed and this is the program that does the extraction and indexing. Advice on making this new version available and active are in order.
Max
Max TenEyck Woodbury max@mtew.isa-geek.net writes:
P.S. to AJ et al.
There is a _lot_ of documentation embedded in the wine code, but it is hard to find at the moment. I'd like to see it indexed and this is the program that does the extraction and indexing. Advice on making this new version available and active are in order.
This has already been discussed, but documentation on the Windows API doesn't belong in the source code. I've been accepting small amounts of function documentation (which IMHO is pretty much useless) along with implementations, but I'm not going to accept significantly more than that. This is why you were directed to do this as a separate project.
On 02/27/2011 02:49 PM, Alexandre Julliard wrote:
Max TenEyck Woodburymax@mtew.isa-geek.net writes:
P.S. to AJ et al.
There is a _lot_ of documentation embedded in the wine code, but it is hard to find at the moment. I'd like to see it indexed and this is the program that does the extraction and indexing. Advice on making this new version available and active are in order.
This has already been discussed, but documentation on the Windows API doesn't belong in the source code. I've been accepting small amounts of function documentation (which IMHO is pretty much useless) along with implementations, but I'm not going to accept significantly more than that. This is why you were directed to do this as a separate project.
But it _does_ belong someplace in the repository and there is already a lot of it embedded.
I'm also not sure that what is in there already can really be called documentation of the _Windows_ API. Rather it is documentation of what we _think_ the API is. That is a small but important difference.
I'd also like clarification on why you think it does _not_ belong in the source code. Some projects insist that documentation _has_ to be part of the source code so that it will be properly maintained.
Max
Max TenEyck Woodbury max@mtew.isa-geek.net writes:
I'd also like clarification on why you think it does _not_ belong in the source code. Some projects insist that documentation _has_ to be part of the source code so that it will be properly maintained.
That's because in most projects the API is defined by the implementation, and when you change the code you want to update the documentation accordingly. The Windows API is defined by Microsoft and is independent of the Wine source. If you want to store it along with the code you'd have to put it inside the Windows source.
The other reason is that a decent documentation of the Windows API would be huge; look at how much information there is on MSDN, and that's still incomplete. It's completely impossible to maintain something of that size in the middle of the source code. As long as it's inside the source, it will just be one or two sentences per function, and maybe a list of parameters. That's not useful documentation.
The reality is that this is not going to happen; nobody is going to invest the time to write real documentation for even a subset of the API. There's just no point, and MSDN is good enough for most needs. And I'm not interested in developing infrastructure for something that won't happen. If you want to prove me wrong, start writing it. Once you have properly documented 100 functions, we can discuss what extra infrastructure is needed for the remaining 50,000.
On 02/27/2011 05:55 PM, Alexandre Julliard wrote:
... If you want to prove me wrong, start writing it. Once you have properly documented 100 functions, we can discuss what extra infrastructure is needed for the remaining 50,000.
Deal on the 100!
Max
On 02/27/2011 05:55 PM, Alexandre Julliard wrote:
The other reason is that a decent documentation of the Windows API would be huge; look at how much information there is on MSDN, and that's still incomplete. It's completely impossible to maintain something of that size in the middle of the source code. As long as it's inside the source, it will just be one or two sentences per function, and maybe a list of parameters. That's not useful documentation.
Hmm. Reviewing c2man.pl: The reason there are only one line comments on the parameters is because that is all the extraction program allows.
I had access to commercial grade source code for some years (_NOT_ Microsoft!) and the library function documentation was indeed in the source files and there was a program that extracted the documentation and that was published and sold.
So, I have to disagree that the situation is impossible. Yes, it is _hard_ to do, and duplicating MSDN should not be the goal. If done right the embedded documentation should add value to the code. Such things as what has and has not been implemented and _why_ might be helpful. It might even be useful to describe _how_ some of the stuff is done.
Oh, and the total amount is indeed huge, but each piece is not. It's just that there are _lots_ of pieces. The way to eat an elephant is one bite at a time...
Max
Am 27.02.2011 20:37, schrieb Max TenEyck Woodbury:
I've picked up Perl in the last couple weeks. An interesting language with lots of adopted features. It's been easy to learn, so I think I will _not_ need help with the language itself, but I will listen to any advice.
When i started with Wine developing i tackled winemaker which is also in perl. I also had to learn Perl for it, so i know you situation. Perl is truely cool, but the "inline" use of RegEx is sometimes confusing (So are $_ and friends) and i hate to use curly brackets for every "if".
The c2man.pl code is extensive and sparsely commented. In order to understand what it does, I've made a transcription of it with a more compact style and lots more comments. I check the rewrite against the source code so there should not be any serious errors. There are also a number of what I believe to be defects in the original and places where my comments may be inappropriate or my style may be very objectionable. _This_ is what I need help with.
Would someone be willing to review my rewrite? If so, send me e-mail so I can arrange to get a copy of it to you.
Remember that you won't get one big patch in at once, you need to split it up later.
P.S. to AJ et al.
There is a _lot_ of documentation embedded in the wine code, but it is hard to find at the moment. I'd like to see it indexed and this is the program that does the extraction and indexing. Advice on making this new version available and active are in order.
I think the idea of building upon the existing "documentation" somewhere else has a better chance than the "deal on the 100"
On 02/28/2011 08:08 AM, André Hentschel wrote:
Am 27.02.2011 20:37, schrieb Max TenEyck Woodbury:
I've picked up Perl in the last couple weeks. An interesting language with lots of adopted features. It's been easy to learn, so I think I will _not_ need help with the language itself, but I will listen to any advice.
When i started with Wine developing i tackled winemaker which is also in perl. I also had to learn Perl for it, so i know you situation. Perl is truely cool, but the "inline" use of RegEx is sometimes confusing (So are $_ and friends) and i hate to use curly brackets for every "if".
Perl's focus seems to be on compact code. Since I have an existing program to work from, I don't have to learn it all at once. The Perl regex is quite a bit more advanced than some others and I'm happy to learn the new features it present. I find it easy to learn.
Curlies are frustrating if you insist on a style that emphasize them, but I think that is due to the conflict between a 'lots of white space' style and the compact philosophy built into the language. The focus should be on the purpose of the code, not on the syntax of the language.
The c2man.pl code is extensive and sparsely commented. In order to understand what it does, I've made a transcription of it with a more compact style and lots more comments. I check the rewrite against the source code so there should not be any serious errors. There are also a number of what I believe to be defects in the original and places where my comments may be inappropriate or my style may be very objectionable. _This_ is what I need help with.
Would someone be willing to review my rewrite? If so, send me e-mail so I can arrange to get a copy of it to you.
Remember that you won't get one big patch in at once, you need to split it up later.
I was going to try for a whole hog replacement, call it c2man2 or something like that, but I can retro-fit as needed.
P.S. to AJ et al.
There is a _lot_ of documentation embedded in the wine code, but it is hard to find at the moment. I'd like to see it indexed and this is the program that does the extraction and indexing. Advice on making this new version available and active are in order.
I think the idea of building upon the existing "documentation" somewhere else has a better chance than the "deal on the 100"
Frankly, I believe embedded documentation is the way to go. It is _not_ a panacea, but it is better than trying to maintain a separate set of functional documentation. I have seen cases where it worked. Not great but OK. I tried the separate document approach and got _very_ frustrated, and _no_one_ was really interested.
Max
Am 28.02.2011 17:20, schrieb Max TenEyck Woodbury:
I think the idea of building upon the existing "documentation" somewhere else has a better chance than the "deal on the 100"
Frankly, I believe embedded documentation is the way to go. It is _not_ a panacea, but it is better than trying to maintain a separate set of functional documentation. I have seen cases where it worked. Not great but OK. I tried the separate document approach and got _very_ frustrated, and _no_one_ was really interested.
Yeah, so let's see how interested people will be in the new aproach. (Also OK might not be enough for Wine)
On 02/28/2011 11:34 AM, André Hentschel wrote:
Am 28.02.2011 17:20, schrieb Max TenEyck Woodbury:
I think the idea of building upon the existing "documentation" somewhere else has a better chance than the "deal on the 100"
Frankly, I believe embedded documentation is the way to go. It is _not_ a panacea, but it is better than trying to maintain a separate set of functional documentation. I have seen cases where it worked. Not great but OK. I tried the separate document approach and got _very_ frustrated, and _no_one_ was really interested.
Yeah, so let's see how interested people will be in the new aproach. (Also OK might not be enough for Wine)
Hmm.
First, it is _not_ a new approach. It has literally decades of application. I first encountered it in the '80s and it was well entrenched even then. Such people as D. Knuth have much to say on the subject. It is not even new to Wine. There is a lot of embedded documentation already. It just is not being maintained.
Second, OK is better than nothing. I say it is OK because I have actually used such a system. It is a pain to maintain, but the results are usually very good. While the stuff I did never reached the public (It got hung at the informal Q/A stage), other similar material was sold at a profit and was generally rated as very good to excellent. Again, the reason I call it OK is because of the amount of work required.
Max
On 2 March 2011 00:32, Max TenEyck Woodbury max@mtew.isa-geek.net wrote:
First, it is _not_ a new approach. It has literally decades of application. I first encountered it in the '80s and it was well entrenched even then. Such people as D. Knuth have much to say on the subject.
I don't think anyone is arguing that it is a new concept, or even that it is a bad idea.
It is not even new to Wine. There is a lot of embedded documentation already. It just is not being maintained.
I think what's important to note is that there's a big difference between documenting Wine and documenting the API that Wine implements. If it makes sense for a 1 or 2 line documenting comment to go in to the code that explains the purpose of a function or a variable, then I'm sure AJ would not have an issue with that; but if you're looking at sticking the MSDN articles for win32/win64 into the Wine source, then that's: * bloating the code; * difficult to maintain (i.e., when MS decides to arbitrarily change the way the API works); * not necessary; and * generally a bad idea
Max TenEyck Woodbury max@mtew.isa-geek.net writes:
Frankly, I believe embedded documentation is the way to go. It is _not_ a panacea, but it is better than trying to maintain a separate set of functional documentation. I have seen cases where it worked. Not great but OK. I tried the separate document approach and got _very_ frustrated, and _no_one_ was really interested.
As I've explained, embedded documentation is not going to happen. And the reason no one is interested is not because it's separate from the source, it's because documenting the Windows API is a huge and boring task, and there's no real need for it.
-
Alexandre Julliard -
André Hentschel -
Ben Klein -
Max TenEyck Woodbury