Andrei's Google Talk

[Johannes Pfau]

On 16.08.2010 04:53, Walter Bright wrote:
> BCS wrote:
>>>> One major aspect in my changes is that there should be no hardcoded
>>>> output: everything can be redefined through macros, though sane
>>>> defaults
>>>> should be provided. Example:
>>>> DDOC_DECLARATION_SEMICOLON=;
>>>> DDOC_FUNCTION_VARARGS=...;
>>>> DDOC_FUNCTION_COMMA=,;
>>> This seems excessive.
>>>
>>
>> Unless you are setting up a new output format, you will never see
>> them. In that light, it doesn't seem excessive to me.
> 
> Adding features because one can isn't good enough. One should only add
> features if they fill a real need. I don't see a point to things like a
> macro for a ;.
The macro for the ; is needed because you might want to strip it out in
the final output. With hardcoded ; this is not easily doable. If you
look at the posted examples you will see that I hide the ; for most
types. This is the only way to achieve something like <span
class="ddoc_semicolon">;</span> which now allows all kinds of css stuff.
The xml output for example completely ignores semicolons and commas,
because they don't make sense there.

<returns>void</returns>
<name>testFunction</name>
<parameters>
  <parameter>
    <type>int</type>
    <name>i</name>
  </parameter>
<parameters>...

Also consider that all macros have sane defaults. No one is required to
redefine them if it's not needed. In fact most macros default to a
simple $0 and unless you redefine these you'll never come across them.

I agree though that there are lots of macros, maybe too many. But it's
hard to find the point between too few and too many. This remembers me,
that there is another limitation with the macro system. Consider for
example:

DDOC_CLASS
    DDOC_PROTECTION

DDOC_FUNTION
    DDOC_PROTECTION

In the DDOC_PROTECTION macro you never know whether this is the
protection for the function or for the class. If you need different
output for DDOC_PROTECTION depending on that, you'll have to define
DDOC_CLASS_PROTECTION and DDOC_FUNCTION_PROTECTION or you have to
generate xml first
<ddoc_class><ddoc_protetion>private</ddoc_protetion></ddoc_class> and
process this xml further, because with xml you can extract the parent
elements.
I know this is by design, and it's not a huge problem. But it means you
need even more macros if you want to make rich output possible without a
custom post processor.

I know that the phobos problem is not directly a problem of ddoc. I just
mentioned it because it also makes generating documentation for other
formats harder. These phobos macros should maybe be moved to the
std.ddoc file. But then we have custom phobos macros which must be
redefined for generating a different output format and if every project
defines there own macros like that, making .ddoc files to output to
different formats soon becomes a mess. I agree that macros to output
tables etc are needed though. But it's important that not every project
defines it's own table macros.

And one more problem, though not directly related to the macro system:
If one really documented code in a WYSIWYG way and would not think he
might be generating html, he could use <,> and &. This would definitely
break html, which means you must make assumptions about the final output
format in the documentation or you might break it.

-- 
Johannes Pfau