On 2013-12-31 01:05, Sönke Ludwig wrote:
Also, the official first four goals of DDOC are:
1. It looks good as embedded documentation, not just after it is
extracted and processed.
It certainly does not. Just have a look at the top of std.algorithm or
std.uni. Hundreds of lines of Ddoc madness.
2. It's easy and natural to write, i.e. minimal reliance on <tags> and
other clumsy forms one would never see in a finished document.
Fails again. As soon as you need something more advanced than the
standard sections you need to use macros. The macros are just as tags,
just with a different syntax and name.
3. It does not repeat information that the compiler already knows from
parsing the code.
You sure need to do if you want good documentation. Take a look at
std.algorithm, it has over 300 lines of Ddoc code to create a symbol
table that Ddoc should be able to automatically generate.
4. It doesn't rely on embedded HTML, as such will impede extraction
and formatting for other purposes.
As far as I know this isn't very useful. For the other formats we use,
like PDF, it uses the HTML output as a base.
To me it looks like it failed on all four of these goals.
Using $(XREF), $(TABLE $(TR $(TD ...))), $(LINK a b) $(D ...) and so on
is nothing but markup. If we go that route, we could as well remove all
syntax, except for the macros:
$(SUMMARY ...)
$(SECTION See_Also
...
)
$(PARAMS
$(PARAM x ...)
$(PARAM y ...)
)
$(SECTION Example
$(CODEBLOCK
...
)
)
But you added the syntax for a reason back then (readability ...and
writability). And the same goes for the auto-detection of identifiers. I
think the only problem is that the default would have been better off
the other way around.
I completely agree.
--
/Jacob Carlborg
