Library standardization

[Sean Kelly]

== Quote from Walter Bright (newshound1 at digitalmars.com)'s article
> 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.

Out of curiosity, would you advocate having public class members that were
not intended to be a part of the class interface?  I haven't been able to think
of a reason why I would.  The package attribute seems to cover every instance
where I'd want to expose some special functionality outside a module.

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

Sounds like more of a fancy header generator.  I know that I tend to look at
source code before documentation, for example, so there is some value in
having that code be easily readable.  And until I began running a pretty
printer on the generated headers in Tango, we did receive fairly regular
complaints that the headers weren't easily readable.  But that said, I'm not
sure there's any reason to have pretty printed headers be a compiler feature.
Certainly not if doing so is unnecessarily complicated at any rate.


Sean