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

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

While I'm thinking of it, one other thing that needs to be documented
is the dependency on ElementTree. What's the oldest required version?

Obviously it should be a non-issue for Python2.5, but for those who
have 1.3 or 2.4, they need to know that external library needs to be
installed, and if they happen to have a too-old version already
installed, we should warn them upfront. Perhaps on a successful
import, we should check the version and exit with an appropriate error
message if it's too old.

On Wed, Aug 6, 2008 at 11:37 AM, Waylan Limberg <wa...@gm...> 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/
>
>
> --
> ----
> Waylan Limberg
> wa...@gm...
>



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