Improving ddoc

[Manu via Digitalmars-d]

On 1 January 2015 at 21:51, Walter Bright via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
> On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote:
>>
>> Why is doxygen insufficient? Is there a reason ddoc was invented
>> rather than supporting the practically-industry-standard doxygen
>> format from the start?
>
>
> There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2
> or 3 people used it.
>
> The problem was Doxygen was some add on tool. It was not part of the
> downloadable D package. It couldn't be. Anyone wanting to use Doxygen was
> going to have to:
>
> 1. pray a version exists on the platform they have that D is installed on.
> 2. pray that version was the one the D docs were expecting.
> 3. buy Doxygen.
> 4. download and install Doxygen successfully.
> 5. Doxygen is a large and complex tool - lots of work to understand it.
> 6. expect the D community to provide tech support with "Doxygen is not
> working on my D documents."
>
> The end result was, essentially nobody used Doxygen. In fact, nobody used
> any sort of documentation system, and we know what the result looked like -
> your typical out-of-date, totally wrong, or non-existent normally found with
> C and C++ projects.
>
> Ddoc, being:
>
> 1. always there
> 2. always the correct version
> 3. Ddoc is trivial to learn and use
>
> revolutionized the D documentation. And that's an understatement.

I'm not arguing that it wasn't an excellent decision to include a doc
parser in DMD, but I don't think any of those advantages are
attributed to the ddoc syntax specifically so much as just including
it in the compiler.
I'm sure the ddoc syntax is fine. It's just noisy and hard to read, as
I think we've established to be the popular opinion.

I'm just suggesting that DMD could also parse some useful subset of
doxygen as ddoc shorthand. I don't think parsing doxygen would be
particularly difficult. Basically all the suggestions here so far,
like the markdown bits are valid doxygen.