Get story straight with private symbols

As @aevri previously raised this in !150 (closed), it might be nicer to change our story of how privateness is denoted in BuildStream.

I tend to agree that using underscores for methods and variables which should not be accessed outside of a class/module is going to be better than what we have, even when the class/module itself is already private - and agree that this would follow the principal of least surprise.

Things have gotten worse (my fault) since before 1.0 I rushed in some changes to privatize some things which were not needed, in order to reduce our public API surface. Notably Context and Project have become private modules, and many of the variables which are intended to be accessed for reading outside of these classes still have leading underscores in order to hide these variables from public API, this should no longer be needed.

We still need a distinction between what is local private and API private, where the former is something that is never used outside of the given class, and the latter is something that is not exposed in our public/stable API surface.

We should clarify this story as:

• Follow the standard use of underscores for local private entities, even in entirely private modules/classes
• With the exception of variables/methods which are API private but not local private (these must still retain leading underscores)
• Retain our current documentation policy:
  • All API private entities are documented using comments, regardless of whether they are local private or not
  • The only entities which are documented using python docstrings are API public entities

We are already in a bit of a messy state, so I would not be averse to partial patches; ideally though this sort of thing should be tackled as an atomic unilateral activity.