[Grok-dev] meet the Grok 1.0 release team

[Brandon Craig Rhodes]

Martijn Faassen <faassen at startifact.com> writes:

> Docstring project - Brandon Craig Rhodes
>
> Brandon is going to make sure our grokcore.* and grok and martian
> codebases are supplied with copious docstrings.

I have made a first pass at a simple file, the "src/grok/rest.py" file
in Grok trunk.  Take a look at it, and feel free to complain about any
of the following "features" of my work:

 - I made the changes in Grok trunk, rather than a branch, since they
   are cosmetic.

 - I aimed for PEP-8 style.

 - In the comments, I try to indicate why each class is present, rather
   than trying to explain how everything works.  My goal is to help
   newcomers find things more easily and understand what each component
   does, not to explain how the actual code works.

 - I have cleaned up all invisible whitespace, including blank lines at
   the end of the file.

 - I removed obsolete "import" statements.

 - I allowed myself small code tweaks.  For example, the _getAllow()
   "for" loop was previously constructing a new list to iterate over
   every time it was called; now it uses a tuple, which only gets
   allocated once, when the program first runs.

 - The docstrings use restructured text conventions, like surrounding
   words in ``double back-ticks`` to indicate that they are literals.

There.  I'll wait a day or so to field complaints about any of the above
practices before touching any further files. :-) And feel free to
complain about anything else that you see that I did that I forgot to
mention in this list!

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon