[Patches] [ python-Patches-785752 ] Documentation for platform module

[SourceForge.net]

Patches item #785752, was opened at 2003-08-09 08:05
Message generated for change (Settings changed) made by lemburg
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=785752&group_id=5470

Category: Documentation
Group: Python 2.3
Status: Open
Resolution: None
Priority: 5
Submitted By: Bjorn Pettersen (bpettersen)
>Assigned to: Brett Cannon (bcannon)
Summary: Documentation for platform module

Initial Comment:
This is my first time writing module documentation so be 
gentle <wink>. 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

----------------------------------------------------------------------

Comment By: M.-A. Lemburg (lemburg)
Date: 2003-10-14 10:11

Message:
Logged In: YES 
user_id=38388

Looks good :-)

----------------------------------------------------------------------

Comment By: Brett Cannon (bcannon)
Date: 2003-10-14 03:59

Message:
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?

----------------------------------------------------------------------

Comment By: M.-A. Lemburg (lemburg)
Date: 2003-10-13 09:35

Message:
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.

----------------------------------------------------------------------

Comment By: Brett Cannon (bcannon)
Date: 2003-10-12 22:33

Message:
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.

----------------------------------------------------------------------

Comment By: M.-A. Lemburg (lemburg)
Date: 2003-10-12 12:41

Message:
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 ?)


----------------------------------------------------------------------

Comment By: Brett Cannon (bcannon)
Date: 2003-10-12 07:16

Message:
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.

----------------------------------------------------------------------

Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2003-08-15 05:18

Message:
Logged In: YES 
user_id=3066

Marc-Andre, could you please review these docs?
Thanks!

----------------------------------------------------------------------

Comment By: Brett Cannon (bcannon)
Date: 2003-08-11 09:26

Message:
Logged In: YES 
user_id=357491

If this patch gets accepted, please close bug #726911.

----------------------------------------------------------------------

Comment By: Martin v. Löwis (loewis)
Date: 2003-08-09 11:17

Message:
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.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=785752&group_id=5470