classification
Title: The docs of xml.dom.pulldom are almost nonexistent
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, eric.araujo, flomm, flox, python-dev
Priority: normal Keywords: easy, patch

Created on 2012-03-05 16:25 by eli.bendersky, last changed 2012-07-06 03:02 by eli.bendersky. This issue is now closed.

Files
File name Uploaded Description Edit
xml.dom.pulldom.rst flomm, 2012-03-07 00:34
pulldom-documentation.rst eric.araujo, 2012-03-07 11:39 review
xml.dom.pulldom.rst flomm, 2012-03-15 22:16 Updated patch-file after review review
xml.dom.pulldom.rst.patch flomm, 2012-03-16 10:02 Updated patch-file after second review review
Messages (17)
msg154959 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-05 16:25
http://docs.python.org/dev/library/xml.dom.pulldom.html

"embarrassing" is the word I wanted to use, but it's too strong for the title ;-)

Seriously, this module is part of the stdlib, it should at least have *some* documentation.
msg155042 - (view) Author: Florian Mladitsch (flomm) Date: 2012-03-07 00:34
I wrote some documentation with the information I found on http://wiki.python.org/moin/PullDom and some custom examples.
msg155048 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-07 04:53
Thanks, Florian - I will review the patch. At first sight it looks much better than what exists.
msg155075 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-07 11:39
Merged Florian’s version with the original file to create a patch.
msg155598 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-13 12:23
I reviewed the patch in http://bugs.python.org/review/14202/show
msg155974 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-15 22:50
Could you provide a diff?  (instructions in the devguide)
msg155975 - (view) Author: Florian Mladitsch (flomm) Date: 2012-03-15 22:58
It is a diff-file, or am I missing something? I generated the file with 'hg diff > xml.dom.pulldom.rst'
Probably should have given it a '*.patch' file-ending =/
msg155988 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-16 02:30
Ah, right, I just assumed that your .rst file was the full file (like in your first upload), but it is indeed a diff.  Our tools don’t care about the file extension, but they sometimes are useful conventions for humans :)
msg155989 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-16 03:41
Looks good, pending fixing of Éric's comments. Florian, could you do that? We can then proceed to commit (to 3.3) and consider backports.
msg156018 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-03-16 12:42
New changeset 172630a3e6d8 by Eli Bendersky in branch '3.2':
Issue #14202: Greatly enhance the documentation of xml.dom.pulldom.
http://hg.python.org/cpython/rev/172630a3e6d8

New changeset 5d118a154ba3 by Eli Bendersky in branch 'default':
Issue #14202: Greatly enhance the documentation of xml.dom.pulldom.
http://hg.python.org/cpython/rev/5d118a154ba3
msg156019 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-16 12:44
I committed the patch after some minor modifications, to 3.2 and 3.3

Florian, thanks for the contribution!
msg156036 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-16 14:31
Thanks to you both, the new docs are greatly better!

Eli, why not backporting to 2.7 too?  It has the same rules and should get the same attention as 3.2.

BTW, when you nest class/method directives, you needn’t repeat the class name in the method directives:

  .. class:: DOVEventStream(stream, etc)

     .. method:: getEvent(blah)

A few nits you may want to avoid in future patches:
- The constants in the methods doc don’t use data markup
- s/ie./i.e./
- I’d say “Unicode string”, not “unicode string” (referring to the concept/standard, not the old class)
msg156047 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-03-16 14:52
New changeset 1a740ea4f2a1 by Eli Bendersky in branch '3.2':
Issue #14202: some additional doc fixes
http://hg.python.org/cpython/rev/1a740ea4f2a1

New changeset b2e27f21760e by Eli Bendersky in branch 'default':
Issue #14202: some additional doc fixes
http://hg.python.org/cpython/rev/b2e27f21760e
msg156048 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-16 14:57
Éric, thanks for the comments - all fixed.

As for 2.7, it's just laziness really. Committing to both 3.2 and 3.3 is trivial since it's a simple merge. For 2.7 it's more complicated since it's an unrelated branch, and the code samples have to be fixed as well (the current ones use Python 3.x syntax).

So I wouldn't object for someone to backport it to 2.7, but I don't deem it very important. If it was a bug fix, I would bother, but for documentation... not really :-)
msg156055 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-16 15:35
I understand :)  I’ll do it.  I value doc as much as code, it’s also delivered faster to the users, and there are a lot of Python 2 users out there, so porting doc fixes to 2.7 is really worth it.
msg156854 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-26 18:53
There was a patch for the docs (+ other stuff) in issue #7635 as well. It can be integrated, if relevant.
msg163901 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-06-25 06:09
Unassigning; I have to use my Python time for distutils bugs, or doc bugs for modules I actually like (I’m no fan of XML nor DOM :).  I would politely insist that doc fixes have to get backported to 2.7 unless it would be really bothersome (like a big change to IO docs done by Antoine and not backported).
History
Date User Action Args
2012-07-06 03:02:26eli.benderskysetstatus: open -> closed
2012-06-25 06:09:32eric.araujosetassignee: eric.araujo -> docs@python
messages: + msg163901
2012-03-26 18:53:12eli.benderskysetmessages: + msg156854
2012-03-26 17:43:18r.david.murraylinkissue7635 superseder
2012-03-16 15:35:28eric.araujosetstatus: closed -> open
assignee: docs@python -> eric.araujo
messages: + msg156055

versions: + Python 2.7
2012-03-16 14:57:34eli.benderskysetmessages: + msg156048
2012-03-16 14:52:48python-devsetmessages: + msg156047
2012-03-16 14:31:45eric.araujosetmessages: + msg156036
2012-03-16 12:44:37eli.benderskysetstatus: open -> closed
versions: + Python 3.2, - Python 2.7
messages: + msg156019

resolution: fixed
stage: patch review -> resolved
2012-03-16 12:42:02python-devsetnosy: + python-dev
messages: + msg156018
2012-03-16 10:02:23flommsetfiles: + xml.dom.pulldom.rst.patch
keywords: + patch
2012-03-16 03:41:38eli.benderskysetmessages: + msg155989
stage: needs patch -> patch review
2012-03-16 02:30:23eric.araujosetmessages: + msg155988
2012-03-15 22:58:47flommsetmessages: + msg155975
2012-03-15 22:50:26eric.araujosetmessages: + msg155974
2012-03-15 22:16:42flommsetfiles: + xml.dom.pulldom.rst
2012-03-13 12:23:19eli.benderskysetmessages: + msg155598
2012-03-07 11:39:45eric.araujosetfiles: + pulldom-documentation.rst

messages: + msg155075
2012-03-07 04:53:09eli.benderskysetmessages: + msg155048
2012-03-07 00:34:49flommsetfiles: + xml.dom.pulldom.rst
nosy: + flomm
messages: + msg155042

2012-03-05 16:25:18eli.benderskycreate