Library standardization

[Bill Baxter]

Walter Bright wrote:
> Bill Baxter wrote:
>>> The human-readable form is the ddoc output.
>> I find it much easier to open up a header file in my text editor to 
>> search for the functions I'm looking.
>> Easier than it is to go over to my browser and hope that the 
>> documentation exists and is complete.
>> I can also run grep on files easily from within my editor to search 
>> for patterns in text files.  My browser can't do that.
>>
>> But maybe ddoc could be enhanced to
>> 1) generate doc stubs for *all* public memebers, not just the ones the 
>> author remembered to document.
> 
> It deliberately does not do that, because this allows the library writer 
> to have some exposed public members that are not part of the official 
> API for it. The official API he should provide ddoc comments for, even 
> if they are nothing more than:
> 
>    ///
>    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 ddoc should have is a special comment tag to *supress* doc 
generation for a particular public member.

>> 2) generate plain text .d files with just doc comments and function 
>> signatures etc.
> 
> But that's what ddoc is for. BTW, there's nothing about ddoc that forces 
> the output to be html. You can write a .ddoc macro file which will cause 
> ddoc to generate plain text.

Right, that's what I meant.  That would be great I think.  And it would 
strip out all the macro junk to make the doc comments truly human 
readable.   Maybe replace $(B foo) with *foo* and $(I foo) with /foo/,  etc.

>> But I think it would be easier to make -H generate nice output than 
>> doing those two.
> 
> The whole point of ddoc is to create nice human readable output, and the 
> point of .di is to generate fast, precompiled 'headers'. I don't 
> understand the argument for a third option.

The argument is that I would rather have plain text format documentation 
that I can read easily in my text editor.  I'm a programmer.  I like to 
work inside my text editor.  Header files do that pretty well in C++.

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.

> Perhaps what you're asking for is a D source code pretty-printer?

Not really.

--bb