View mode: basic / threaded / horizontal-split · Log in · Help
August 07, 2010
Re: Documentation generation
bearophile wrote:
> Walter has said that putting ddoc inside the compiler helps keep ddoc
> uniform, so people don't invent/use something different. In theory this is a
> nice purpose, but in practice I have seen lot of people use other
> documentation means for D, Doxygen. Walter seems to ignore how much often
> such other systems are used instead of ddoc.

It's fine if people choose to use other documentation systems. Ddoc, though, 
sets a minimum standard, and it's always there, requires no additional installs, 
is always synced to the compiler, is always on every platform D is, etc.

My experience with languages that do not have built in doc abilities is, by and 
large, only a tiny minority of programmers use a doc system. Having to research, 
download, install, read the manual, address incompatibilities, etc., takes 
effort and the reality is that by making such effort close to zero it greatly 
encourages people to use it.

The same goes for unit tests.

For another example, back in the 80's, it was commonplace for people to dis the 
C text preprocessor as "not a real macro system". Those who wanted a better one 
were advised to "just use m4". How many people using C or C++ today use m4 as 
the preprocessor? Zilch. The C preprocessor was good enough to get the job done, 
it was always there, always ready, and that was that.

(Note that I'm not defending the preprocessor, I'm just illustrating the power 
of having something built in as opposed to being a separate tool.)
August 07, 2010
Re: Documentation generation
On 08/07/2010 02:53 PM, Walter Bright wrote:
> bearophile wrote:
>> Walter has said that putting ddoc inside the compiler helps keep ddoc
>> uniform, so people don't invent/use something different. In theory
>> this is a
>> nice purpose, but in practice I have seen lot of people use other
>> documentation means for D, Doxygen. Walter seems to ignore how much often
>> such other systems are used instead of ddoc.
>
> It's fine if people choose to use other documentation systems. Ddoc,
> though, sets a minimum standard, and it's always there, requires no
> additional installs, is always synced to the compiler, is always on
> every platform D is, etc.
>
> My experience with languages that do not have built in doc abilities is,
> by and large, only a tiny minority of programmers use a doc system.
> Having to research, download, install, read the manual, address
> incompatibilities, etc., takes effort and the reality is that by making
> such effort close to zero it greatly encourages people to use it.
>
> The same goes for unit tests.
>
> For another example, back in the 80's, it was commonplace for people to
> dis the C text preprocessor as "not a real macro system". Those who
> wanted a better one were advised to "just use m4". How many people using
> C or C++ today use m4 as the preprocessor? Zilch. The C preprocessor was
> good enough to get the job done, it was always there, always ready, and
> that was that.
>
> (Note that I'm not defending the preprocessor, I'm just illustrating the
> power of having something built in as opposed to being a separate tool.)

Boost's preprocessor library is a powerful exhibit in favor of your 
argument. I think I wouldn't be mistaken to say that everything it does 
can be done much easier and much better, plus with m4 you can do a lot 
other things of interest. But the Boost preprocessor library wins 
because "it's there".


Andrei
August 08, 2010
Re: Documentation generation
On Sat, 07 Aug 2010 01:55:35 -0700, Jonathan M Davis wrote:

> On Friday 06 August 2010 20:06:59 Bernard Helyer wrote:
>> On Sun, 01 Aug 2010 13:22:53 -0700, Walter Bright wrote:
>> > 1. Being a defined part of D means it's ALWAYS there. That means
>> > there won't be D compilers without ddoc.
>> 
>> /me waves.
>> 
>> I'm writing a D compiler, and have zero plans to add DDoc support. I
>> couldn't do it well enough for me to waste my time on it.
> 
> Well, that's your choice, but then you haven't followed the D spec in
> that regard, so your compiler wouldn't be properly standard D. 

Nope. But it doesn't matter. It doesn't affect the code built or 
generated, and that's my focus -- at least for the foreseeable future.

I'm writing a compiler, not a half-arsed documentation generator (because 
if I wrote the DDoc stuff, that's exactly what it would be).
August 08, 2010
Re: Documentation generation
On 08/08/2010 01:32, Bernard Helyer wrote:
> Nope. But it doesn't matter. It doesn't affect the code built or
> generated, and that's my focus -- at least for the foreseeable future.
>
> I'm writing a compiler, not a half-arsed documentation generator (because
> if I wrote the DDoc stuff, that's exactly what it would be).

Sounds cool. What are you writing it in and is it going to be public?

-- 
My enormous talent is exceeded only by my outrageous laziness.
http://www.ssTk.co.uk
August 08, 2010
Re: Documentation generation
== Quote from Bernard Helyer (b.helyer@gmail.com)'s article
> I'm writing a compiler, not a half-arsed documentation generator (because
> if I wrote the DDoc stuff, that's exactly what it would be).

I'll concur with Walter.  I think that sometimes power users of a given
tool/feature fail to realize that very often simple, good enough and works out of
the box beats well-designed, feature-packed, efficient, but a PITA to set up and
use, overkill for simple cases, and not available out of the box.  I understand
treating ddoc as a low priority feature, but **please** support it eventually, as
the whole point of it is that it's just there on any implementation (nothing
separate to download/configure) and just works for the simplest 80-90% of cases
even if its deficiencies become obvious in the last 10-20%.

In general I also think that DDoc's evolution is actually good design strategy.  I
wish more tools were designed by pinning down how the simplest 80-90% of cases
should work first, treating that as a constraint and then figuring out how to make
the most complicated 10-20% work within the constraint.  Designing with
"everything must be possible" as the first goal encourages overengineering such
that users with simple needs end up reinventing the wheel because it's the path of
least resistance.  For example, I'd probably never use Ddoc if I had to use XML
for it.
August 08, 2010
Re: Documentation generation
On Sun, 08 Aug 2010 02:02:28 +0100, div0 wrote:

> On 08/08/2010 01:32, Bernard Helyer wrote:
>> Nope. But it doesn't matter. It doesn't affect the code built or
>> generated, and that's my focus -- at least for the foreseeable future.
>>
>> I'm writing a compiler, not a half-arsed documentation generator
>> (because if I wrote the DDoc stuff, that's exactly what it would be).
> 
> Sounds cool. What are you writing it in and is it going to be public?

D. It's already public[1], but there's not a lot to show yet. You can 
compile `int main() { return 42; }`, but that's about it, so far. :P

[1]:http://github.com/bhelyer/SDC
August 08, 2010
Re: Documentation generation
On Sun, 08 Aug 2010 02:22:30 +0000, dsimcha wrote:

> == Quote from Bernard Helyer (b.helyer@gmail.com)'s article
>> I'm writing a compiler, not a half-arsed documentation generator
>> (because if I wrote the DDoc stuff, that's exactly what it would be).
> I understand treating ddoc as a low priority feature,
> but **please** support it eventually,

Well, sure, once basically *everything* else is done, I'll probably poke 
at it. But it is a very low priority.
August 14, 2010
Re: Documentation generation
Sun, 08 Aug 2010 02:22:30 +0000, dsimcha wrote:

> == Quote from Bernard Helyer (b.helyer@gmail.com)'s article
>> I'm writing a compiler, not a half-arsed documentation generator
>> (because if I wrote the DDoc stuff, that's exactly what it would be).
> 
> I'll concur with Walter.  I think that sometimes power users of a given
> tool/feature fail to realize that very often simple, good enough and
> works out of the box beats well-designed, feature-packed, efficient, but
> a PITA to set up and use, overkill for simple cases, and not available
> out of the box.  I understand treating ddoc as a low priority feature,
> but **please** support it eventually, as the whole point of it is that
> it's just there on any implementation (nothing separate to
> download/configure) and just works for the simplest 80-90% of cases even
> if its deficiencies become obvious in the last 10-20%.
> 
> In general I also think that DDoc's evolution is actually good design
> strategy.  I wish more tools were designed by pinning down how the
> simplest 80-90% of cases should work first, treating that as a
> constraint and then figuring out how to make the most complicated 10-20%
> work within the constraint.  Designing with "everything must be
> possible" as the first goal encourages overengineering such that users
> with simple needs end up reinventing the wheel because it's the path of
> least resistance.  For example, I'd probably never use Ddoc if I had to
> use XML for it.

The problem with ddoc is that even though 1000+ documentation formats 
already existed, he wanted to reinvent his own. The ddoc syntax is 
terrible ad-hoc crap and geared towards html (3.2/4). Has anyone 
seriously tried to generate any non-html documents with ddoc which look 
as good as better than those created with e.g. doxygen?! I've personally 
just filtered out the bad constructs from the sources and rendered with 
the buggy doxygen. Much better. I get nice pdf/tex/man/xml output.
Next ›   Last »
1 2
Top | Discussion index | About this forum | D home