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

[Artem Y. <ne...@gm...>]

Yep, I'll update doc strings by myself. Thanks for the link to PEP 257.
I think extension writers need to know about markdown.etree module 
object, and also, that all data in <inline> tag will be processed by 
inline patterns, other functions, like indentETree is useless for them. 
I think we should write about all this on site in "Writing Extensions" 
section.
Concerning ElementTree version, I made some tests, all versions since 
1.1(including) suitable for us. That means that only 1.0 failed. I'll 
add version check to importETree function.
Python 2.5 uses ElementTree 1.2.6.

Waylan Limberg wrote:
> 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/
>
>
>