[phobos] Initial Phobos style guide proposal

[Jonathan M Davis]

On 2011-03-31 08:25, David Simcha wrote:
> On Thu, Mar 31, 2011 at 11:21 AM, Jacob Carlborg <doob at me.com> wrote:
> > - All public declarations should have proper ddoc documentation.
> > 
> > 
> > And protected methods as well, they're a part of the API just as much as
> > the public methods.
> 
> Somewhat agree, but sometimes you make a protected method to be overridden
> internally in your hierarchy, but it's not designed to be messed with by
> external clients.  Omitting ddoc for it sends a strong "don't mess with
> this" message.

Maybe it would be better to say something like "All declarations which are 
part of the public API of a type or module should have proper ddoc 
documentation." Then, the issue of public vs protected is kind of moot as far 
as documentation goes. The key is that any functions which are public and/or 
intended to be useable by anyone using Phobos should be properly documented.

In most cases though, a protected function internal to a hierarchy shouldn't 
be necessary in Phobos. I wouldn't expect much - if anything - in the way of 
inter-module hierarchies where it makes any sense to hide any protected 
functions. And if it's changed so that private functions are overridable 
(which may or may not happen - 
http://d.puremagic.com/issues/show_bug.cgi?id=4542 ), then you wouldn't need 
to use protected for overriding inside a module anymore. So, in general, I 
don't think that protected functions which aren't meant to be overridden by 
anything than other Phobos code make much sense.

The key thing though is that the API be properly documented.

- Jonathan M Davis