Re: [Python-markdown-discuss] GSoC version merged to mainline

[Waylan L. <wa...@gm...>]

Artem,

I have finally got a chance to start looking at your work more closely
and really appreciate the time and effort you put into it. I still
need to wrap my head around a few things, but it looks good so far.

Looking through your code, I noticed a few missing or problem doc
strings. I thought you might want to clean them up yourself. If you
haven't already, I'd suggest reading [PEP 257][] first as a guideline.
No doubt you'll notice that we haven't kept to that strictly, but I've
been making an effort to improve in that area recently. In fact, a few
months back I went through and added a significant amount of missing
doc strings.

My policy has been that any class/method/function that extension
writers are likely to use should get a very thorough docstring
spelling everything out, and anything else can have a one-liner
(except that _private methods do not need one). So, for example, would
an extension writer need to use some of your etree helper functions to
build his/her elements for inclusion in the tree? I'm not sure, and I
don't find any hints in the existing docstrings.

Also, in PEP 257 you may want to note this comment with regard to
one-liners (although the principle should apply to all docstrings):

> The docstring is a phrase ending in a period. 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 ...".

It appears that most of your docstrings get that wrong, although its
not too hard to fix. You might want to run a spellcheck on your
docstrings as well ( I saw a few "retruns").

Oh, and one final point, the docstrings should all use markdown
formatting - especially the long ones - for reasons that should be
obvious. I didn't notice any specific problems there, but figured it's
worth pointing out.

I realize this may seem a little nitpicky, and I get the impression
Yuri isn't too worried about it, but it has been something others have
complained about in the past and I really want to get it right before
we release 2.0 final.

[PEP 257]: http://www.python.org/dev/peps/pep-0257/


-- 
----
Waylan Limberg
wa...@gm...