[MERGE] Clarify use of underscores in HACKING

[Martin Pool]

On 7/19/07, Robert Collins <robertc at robertcollins.net> wrote:
> On Thu, 2007-07-19 at 19:59 +1000, Ian Clatworthy wrote:
> >
> > 3. pydoctor to recognise a @visibility decorator that takes a string
> > and
> > uses that to override the default visibility value.
>
> I'd rather not use a decorator - decorators run code at load time and
> run time.
>
> Use
> :visibility: or something in the doc string.

Agree.  Maybe :stability: since they're all visible - you can see them
but you shouldn't touch. :-)  Solaris manuals have an 'interface
stability' section.

http://blogs.sun.com/elowe/entry/dangers_of_having_the_source

So we should agree on the values for these and add them to HACKING -
even before or without pydoctor supporting them.  John's list above
sounds good.

-- 
Martin