GSOC Linker project

[foobar]

On Friday, 4 May 2012 at 22:38:27 UTC, H. S. Teoh wrote:
> 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

This all amounts to the issues you have with the current 
implementation of DDoc which I agree needs more work.
The solution then is to fix/enhance DDoc.
Doxygen for instance has a setting to output all declarations 
whether documented or not, thus addressing your main point.

The projects you speak of I assume are written in C/C++? Those 
tend to have poor documentation precisely because people assume 
the header files are enough.
C/C++ requires you to install a 3rd party doc tool and learn that 
tool's doc syntax - effort that people are too lazy to invest.

In the Java world the syntax is standardized, the tool comes 
bundled with the compiler, all tools speak it and IDEs will even 
insert empty doc comment for you automatically. Frankly it takes 
effort to *not* document your code in this setting.
D provides DDoc precisely because it strives to provide the same 
doc friendly setting as Java.