On Sat, May 05, 2012 at 12:07:16AM +0200, foobar wrote: > On Friday, 4 May 2012 at 21:11:22 UTC, H. S. Teoh wrote: > >Exactly. And while we're at it, *really* strip unnecessary stuff from > >.di files, like function bodies, template bodies, etc.. That stuff is > >required by the compiler, not the user, so stick that in the object > >files and let the compiler deal with it. The .di file should be ONLY > >what's needed for the user to understand how to use the library. > > > > > >T > > You contradict yourself. > The purpose of di files *is* to provide the compiler the required > info to use the binary object/library. If you want human readable > docs we already have DDoc (and other 3rd party tools) for that. > If you don't like the default HTML output (I can't fathom why) you > can easily define appropriate macros for other output types such as > TeX (and PDF via external converter), text based, etc..
HTML is a stupid format, and ddoc output is not very navigable, but that's beside the point. I prefer to be reading actual code to be 100% sure that ddoc isn't leaving out some stuff that I should know about. All it takes is for somebody to leave out a doc comment and a particular declaration becomes invisible. (For example, std.uni was next to useless before I discovered that it actually had functions that I needed, but they didn't show up in dlang.org 'cos somebody failed to write doc comments for them.) I've seen too many commercial projects to believe for a moment that documentation is ever up-to-date. It depends on the library authors to provide ddoc output formats in a sane, usable format. Whereas if the compiler had a standardized, uniform, understandable format in well-known code syntax, that's a lot more dependable. It's often impossible to debug something if you don't get to see what the compiler sees. I suppose you could argue that leaving out function bodies and stuff amounts to the same thing, but at least the language's interface for a function is the function's signature. When you have a .di file, you're guaranteed that all public declarations are there, and you can see exactly what they are. Of course, IF ddoc can be guaranteed to produce exactly what's in a .di file, then I concede that it is sufficient this purpose. T -- Recently, our IT department hired a bug-fix engineer. He used to work for Volkswagen.