[MERGE] Clarify use of underscores in HACKING

[Michael Hudson]

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.

Cheers,
mwh