[PING][MERGE] help topics

[John Arbash Meinel]

Aaron Bentley wrote:
> Goffredo Baroncelli wrote:
>>> +def add_topic(topic, detail, summary):
>>> +    """Add documentation for a new topic.
>>> +
>>> +    :param topic:  Name of documentation entry.
>>> +    :param detail:  Function or string object providing detailed
>>> +    documentation for topic.  Function interface is detail(topic, outfile).
>>> +    :param summary:  String providing single-line documentation for topic.
>>> +
>>> +    """
>>> +    _HELP_TOPICS[topic]=(detail, summary)
> 
> Wouldn't it make sense to use a Registry for this?

It would, but this specific branch pre-dates Registry. I'd rather see it
merged and cleaned up, as it has already been in the wild for ~2 months now.

> 
>>> +
>>>  class cmd_revert(Command):
>>>      """Revert files to a previous revision.
>>>  
>>> @@ -2485,23 +2486,25 @@
>>>  class cmd_help(Command):
>>>      """Show help on a command or other topic.
>>>  
>>> -    For a list of all available commands, say 'bzr help commands'."""
>>> +    For a list of all available commands, say 'bzr help commands'.
>>> +    """
> 
> There seem to be a lot of unrelated changes here.  These sorts of
> changes are hostile to branches, and I have a lot of outstanding branches.

What outstanding branches do you have? I have a couple reasons for
asking. First, we should try and keep things being integrated often, so
we don't have large merge issues. Plus, it means bzr core is constantly
improving. Second, I'd really like to see changes like this happen.
There are a few code cleanup issues that I would like to see done, but
as long as we avoid them because we don't want them to cause merge
conflicts, then the code never gets cleaned up.

> 
>>>  class RevisionSpec_revno(RevisionSpec):
>>> +    """Selects a revision using a number.
>>> +
>>> +    Use an integer to specify a revision in the history of the branch.
>>> +    Optionally a branch can be specified. The 'revno:' prefix is optional.
>>> +    A negative number will count from the end of the branch (-1 is the
>>> +    last revision, -2 the previous one). If the negative number is larger
>>> +    than the branch's history, the first revision is returned.
>>> +    examples:
> 
> Aren't we getting away from putting user-facing text in docstrings?
> IIRC, Martin said doing that for BzrNewError was a mistake.
> 
> So I like the idea, but I think this implementation could stand improvement.
> 
> Aaron

Well, we still use the doc string for Commands, so I don't see us moving
away from that right away. We could certainly add stuff like this, but I
don't see it as a reason to block on this. There are lots of other
topics that people have asked for, and it would be nice if the help
system was more thorough.

John
=:->

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20061107/0ff1066a/attachment.pgp