current ddoc state of the art

[Mike Parker via Digitalmars-d]

On 1/2/2015 7:10 AM, Walter Bright wrote:
> On 1/1/2015 1:49 PM, H. S. Teoh via Digitalmars-d wrote:
>> The problem is that this is strictly speaking a hack, not a solution,
>> because in the output it's not tagged as a list. This may not be a
>> problem if the output is HTML for user consumption, but if you're
>> outputting to XML, say, or if your HTML is postprocessed by semantic
>> analysis tools, they will fail to pick up on the fact that this is a
>> list.
>
> I know it's not tagged as a list, but it does show up in the browser as
> a reasonable list.
>
> The thing is, basic documentation can be done in Ddoc without using any
> macros - lists are not used in the vast majority of function
> descriptions. Using:
>
>    $(LIST
>       item1,
>       item2,
>       item3
>     )
>
> for the occasional use is simply not that heinous. Lists can also be
> styled in quite a variety of ways; with a special syntax for them they
> can only be styled one way across the entire document. It turns out that
> Ddoc usage has leaned towards using a lot of custom styling, because
> it's easy to do.

So then Ddoc features become like C++ features -- usage varies across 
projects. Those who hate the visual noise won't use the macros, others 
will use macros all over the place, but they won't necessarily be the 
same from project to project with people defining custom macros.

Personally, I like the simple, macroless form of Ddoc just fine. It's 
what I use for my stuff. But looking at the Phobos docs gives me a 
headache. Contributing to the documentation requires learning the 
difference between all the different macros (XREF,LINK2,FULL_XREF...). 
Not impossible, but it can turn what you think is going to be a simple 5 
minute change into a rather longer process.

The macro system provides a great deal of flexibility, but it sucks in 
terms of readability no matter how it's formatted. The Ddoc generator 
can process it wonderfully -- my brain, not so much. It also doesn't 
encourage any sort of consistency at all. The thing about JavaDoc or 
DOxygen is that no matter which project source I'm looking at, the 
comment tags not only don't get in the way, but if I want to contribute 
I know exactly which tags to use.

Besides, consider how many tasks the macros in Phobos handle that are 
common enough for most projects to need them. Shouldn't that sort of 
thing be built in? Why should we keep putting together LIST macros when 
a list is a very common documentation feature? It's nice to be able to 
redefine that macro for different types of markup output, but I would 
much rather see a standard list tag that simply outputs HTML. I can use 
one of several tools to convert the HTML to something else if I need to.