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.
