[Patches] [ python-Patches-785752 ] Documentation for platform
module
SourceForge.net
noreply at sourceforge.net
Mon Oct 13 03:35:03 EDT 2003
Patches item #785752, was opened at 2003-08-09 08:05
Message generated for change (Comment added) 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: M.-A. Lemburg (lemburg)
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-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
More information about the Patches
mailing list