Library standardization

[Bill Baxter]

Walter Bright wrote:
> Bill Baxter wrote:
>> Walter Bright wrote:
>>>    ///
>>>    void foo();
>>>
>>> which will cause foo() to be included in the ddoc output.
>>
>> That's an unrealistic expectation of developers' diligence.  It's too 
>> easy to forget a method or accidentally leave off a * in the intended 
>> doc comment, turning it into just a plain comment.
> 
> What are the consequences of him forgetting to do so? Nothing disastrous.

Except the poor programmer may end up searching through a dozen modules' 
docs looking for a particular method that they're sure must exist, 
ultimately conclude that the function doesn't exist, and finally waste 
more time reimplementing it.  Only to find out later that it was in some 
module, it just didn't have a doc comment.  I can't recall the specifics 
but I'm pretty sure I've had this exact sequence happen to me before 
with something in Phobos.

>> What ddoc should have is a special comment tag to *supress* doc 
>> generation for a particular public member.
> 
> I don't agree, I think it adds complexity with little benefit.

I think it adds little complexity with significant benefit.


>> I still think making -H a little more usable would be easier, but I 
>> agree that a plain-text DDOC target would be the best way to go.  But 
>> ddoc is too much of a pain if it's going to just silently omit methods 
>> that I or other authors forgot to put a doc comment on.
> 
> I don't think it is asking too much of programmers to at least mark the 
> functions that are part of the public face of their code.

You just can't count on the diligence of programmers.  Especially when 
it comes to documentation or commenting their code.  If it doesn't 
generate a compiler error, many programmers just aren't going to care, 
and many of the ones who do care just won't notice.  Your position is 
completely unrealistic.  Many people don't put /any/ ddoc comments in 
their code.  Is that because they wanted all their methods to be hidden? 
  If I want to use DDoc on their library it would be nice if I could at 
least get the public API out of it.

Any way you slice it, not generating doc for unlabeled public parts is 
just not as useful as generating it.

--bb