Library standardization

Walter Bright newshound1 at digitalmars.com
Mon Apr 21 00:47:47 PDT 2008


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.


> 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 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.



More information about the Digitalmars-d mailing list