[MERGE] Clarify use of underscores in HACKING

[Ian Clatworthy]

Michael Hudson wrote:
> Ian Clatworthy wrote:
> 
>> I'm not sure how flexible pydoctor and friends are in producing "just
>> public" API docs but I'd expect _ things to be hidden in that while I'd
>> expect (c) things to be exposed but marked as "for internal bzrlib use
>> only". Somehow.
> 
> Tell me what you want (algorithmically, please :-) and I can make it
> happen.  pydoctor can detect decorators, and already has some support
> for not documenting things who do not appear in __all__ or whose name
> starts with a '_'.  What I would like is to have two modes, one where
> private things are hidden and one where they are shown and javascript to
> switch between them but that's a way off unless I find a lot more
> pydoctor hacking time all of a sudden.

As you were kind enough to offer, I'll happily describe what I'd like to
see!

1. pydoctor to have an option called --visibility that adds a column
labelled Visibility. Before Kind would be nice, but anywhere would do.
In the section for each symbol, I'd also like the visibility value
appended to the top line after "(source)".

2. Here are the default rules for populating that column:

* no underscores -> public
* 1 underscore -> private
* special names (e.g. __init__) -> public
* other symbols starting with 2 or more underscores -> private

3. pydoctor to recognise a @visibility decorator that takes a string and
uses that to override the default visibility value.

4. (optional) sort the symbols in the tables so that public is first,
private is last and custom visibility values are alphabetically sorted
in between.

We can then define whatever visibility symbols we like, e.g. "protected"
and "package" if we want to explicitly document the fact that some
symbols are for subclass use only, internal bzrlib use only, etc. (I'm
trying to propose an open design that is potentially useful beyond bzr.)

FWIW, I wouldn't bother with the javascript magic for a while either.
It's a really neat idea but sounds more work than it's worth (to me).

Ian C.