[merge] Registry

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

John Arbash Meinel wrote:
>>>>>> +class _LazyObjectGetter(_ObjectGetter):
>>>>>> +    """Keep a record of a future object, and on request load it."""
>>>> Should be "and, on request, load it."
>>> I don't think it's incorrect as originally written, though yours might
>>> be clearer.  Sometimes I try to say "may be clearer as".
> 
> This seems to have too many commas:
> 
> Keep a record of a future object, and, on request, load it.
> 
> How about:
> 
> """Keep a record of a possible object.
> 
> When requested, load and return it.
> """

That's fine by me.

>>>>>> +        If not imported yet, this will import the requested module.
>>>> This has the object of the sentence hidden at the end of it.  I'd
>>>> prefer: "This will import the requested module, if not yet imported"
>>> +1
> 
> Upon first request, the object will be imported. Future requests will
> return the imported object.

I don't think that's accurate; it's not the object that will be
imported, but the module.

Upon the first request, the module will be imported and the object will
be returned.  On subsequent requests, the same object will be returned,
without importing the module.

> The new text is:
> 
> :param key: This is the key to use to request the object later.
> :param obj: The object to register.
> :param help: Help text for this entry. This may be a string or
>         a callable. If it is a callable, it should take two
>         parameters (registry, key): this registry and the key that
>         the help was registered under.
> :param info: More information for this entry. Registry.get_info()
>         can be used to get this information. Registry treats this as an
>         opaque storage location (it is defined by the caller).
> :param override_existing: Raise KeyErorr if False and something has
>         already been registered for that key. If True, ignore if there
>         is an existing key (always register the new value).

"ignore if there is an existing key" sounds funny to me.  "do not check
whether there is an existing key" might be better.

> I'm happy to clean up documentation. Though I'm a little concerned it
> may become one more hoop to jump through before we can merge anything.
> And it is also a place that can be subject to a lot of bike-shedding.

I agree.  Our focus ought to be on making the docs easy to understand.
That should override the desire to make them "beautiful", and may
occasionally override the desire for correct grammar.

So subject-verb-object is the best default, and sentences with lots of
commas probably need to be untangled.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFLwf20F+nu1YWqI0RAgaiAJ4nfIYYvnWWRzv+hO+5xdoETrJGSACePHlK
XpMc97bCCndbJGAq9RYs9kA=
=tOAQ
-----END PGP SIGNATURE-----