Library standardization

[Walter Bright]

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.

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


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

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