Non-public public functions: Conventions for identifying?

[Colin Clark]

Hi Anastasia,

On 2010-11-08, at 10:26 AM, Cheetham, Anastasia wrote:

> At the dev meeting last week, we discussed the fact that there are a number of functions in the framework (and in some components) that are in the public namespace but which are not really intended for use by the general public, and which hence probably shouldn't have official documentation.
> 
> We discussed how we could identify these functions, so that the poor sod writing the documentation doesn't waste time writing things that are best left unsaid. Options included special naming conventions and an agreed-upon comment. The general consensus of those at the dev meeting was a preference for an agreed-upon comment (and NOT a special naming convention), but we wanted to throw it out to the list before we implement it.

I missed the conversation last week, so apologies for asking a question that you no doubt covered during the meeting. Can we identify the various reasons why any of these functions are public but "not intended for the general public?" I imagine the rationale might include functions that are "sneak peek" and subject to change in future releases, but are there any other motivations for making them public but not documenting them?

Colin

---
Colin Clark
Technical Lead, Fluid Project
http://fluidproject.org