[Doc-SIG] Re: Ease of use is #1

[Ka-Ping Yee]

On Mon, 7 Feb 2000, Peter Funk wrote:
> 
> I think, it would be very valuable, if we could come up with a more
> formal description (grammar?) of how this "guessing" markup engine works
> or should work.  
> 
> As long as this wonderful artificial intelligence code build into
> the guessing engine works well, no one has to bother with it.

Let's stay away from the dangerous realm of "guessing" and imagining
that there is any "artificial intelligence" going on.  We do not want
this system to do any fancy thinking at all; it must be dead stupid
in what it does, so that its behaviour is predictable.

As for your formal description, i agree that would be very good.  To
start things off, here are the rules used in the script that generated
the example at http://www.lfw.org/python/SocketServer.html -- there
are just three:

    1.  In a module docstring, any mention of a class defined in
        that module is hyperlinked to the class documentation.

    2.  In a class docstring, any mention of a method defined in
        that class, where the method name is immediately followed by
        an open-parenthesis, is hyperlinked to the method documentation.

    3.  In a class or method docstring, any identifier preceded by
        "self." is set in boldface.

I would probably extend the first rule to allow referring to classes
in other modules (by saying module.class), and add one more rule to
highlight where parameter names are mentioned in function or method
docstrings, and leave it at that.


-- ?!ng