| msg44417 - (view) |
Author: Bjorn Pettersen (bpettersen) |
Date: 2003-08-09 06:05 |
| This is my first time writing module documentation so be gentle . Let me know if I did something wrong and I'll fix and resubmit (compiling the docs sounded like dark magic, so I skipped that part ;-) -- bjorn |
|
|
| msg44418 - (view) |
Author: Martin v. Löwis (loewis) *  |
Date: 2003-08-09 09:17 |
| Logged In: YES user_id=21627 Thanks for this document. It currently does not follow the grammatical conventions. Please use the imperative voice; quoting from PEP 257 It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...". In addition, please indicate where you suggest this documentation to go in the table-of-contents, preferably by means of a patch. |
|
|
| msg44419 - (view) |
Author: Brett Cannon (brett.cannon) * |
Date: 2003-08-11 07:26 |
| Logged In: YES user_id=357491 If this patch gets accepted, please close bug #726911. |
|
|
| msg44420 - (view) |
Author: Fred Drake (fdrake) |
Date: 2003-08-15 03:18 |
| Logged In: YES user_id=3066 Marc-Andre, could you please review these docs? Thanks! |
|
|
| msg44421 - (view) |
Author: Brett Cannon (brett.cannon) * |
Date: 2003-10-12 05:16 |
| Logged In: YES user_id=357491 Ran the docs through texcheck.py and added spaces between function parameters. It looks like it is pretty much just a copy and paste job from the docstrings, right, Bjorn? If so then as long as Bjorn did his copying after 2003-08-05 when I committed some cleanup of the of the docstrings there is no need to check it for correctness in terms of grammar and such. So if Bjorn can verify he copied and pasted the docs after my patch to platform.py I can commit this so Fred can work his LaTeX magic on it. |
|
|
| msg44422 - (view) |
Author: Marc-Andre Lemburg (lemburg) * |
Date: 2003-10-12 10:41 |
| Logged In: YES user_id=38388 Some nits: References to _default_architecture should either get removed or made explicit in that the defaults are listed somewhere in the documentation. I'd suggest to use "reasonable defaults are chosen" since that leaves the details to the module rather than the documentation. References to "True" and "False" should be changed to true and false. The APIs don't use Python 2.1 style boolean singletons and only check for truth values (needed for Python 1.5.2 compatibility and useful in general). _popen is used in the documentation but not explained. I'd suggest to remove these details from the documentation. Apart from that: great job ! (BTW, is there a tool which does this in an automatic way, e.g. in docutils ?) |
|
|
| msg44423 - (view) |
Author: Brett Cannon (brett.cannon) * |
Date: 2003-10-12 20:33 |
| Logged In: YES user_id=357491 OK, I will try to get to the fixes today, MA. Do you want the docstrings changed as well? I can understand doing that for the True/False deal, but not necessarily for _default_architecture. And as for a tool that automates this, I don't know but I was wondering the same thing last night. If not it might be worth it to try to come up with a rough one that at least takes the docstrings, and puts them into a rough LaTeX document that at least spits out a template header and does the function parameter lists and such. In other words get the brain-dead LaTeX conversion stuff out of the way. |
|
|
| msg44424 - (view) |
Author: Marc-Andre Lemburg (lemburg) * |
Date: 2003-10-13 07:35 |
| Logged In: YES user_id=38388 No need to change the doc-strings (the source for all of the APIs in question is included in the same file, so there's no problem). Thanks. |
|
|
| msg44425 - (view) |
Author: Brett Cannon (brett.cannon) * |
Date: 2003-10-14 01:59 |
| Logged In: YES user_id=357491 OK, I made the changes as requested by MAL. Do this good enough to you, MA, to check this in as-is? |
|
|
| msg44426 - (view) |
Author: Marc-Andre Lemburg (lemburg) * |
Date: 2003-10-14 08:11 |
| Logged In: YES user_id=38388 Looks good :-) |
|
|
| msg44427 - (view) |
Author: Brett Cannon (brett.cannon) * |
Date: 2003-10-14 21:49 |
| Logged In: YES user_id=357491 OK, with MAL's blessing I checked in libplatform.tex and added an entry in Doc/lib/lib.text under the generic OS section. Closes bug #726911. Now Fred just has to work his magic. =) |
|
|