Andrei's Google Talk

[Johannes Pfau]

On 15.08.2010 23:27, Walter Bright wrote:
> retard wrote:
>>  - the markup/macro syntax is NIH new.
> 
> Not really. The macro syntax is copied from make. And it's utterly trivial.
> 
> I'd like to know how the macro system is inadequate for generating
> Latex, man, etc. format.

I think it's not a problem with the macro system, but with the few
macros emitted by dmd: There are enough macros for the doc comments
(DDOC_SUMMARY, DDOC_DESCRIPTION, ...) but not for the types. DDOC_DECL,
DDOC_DECL_DD and DDOC_*_MEMBERS are just not enough to extract detailed
information. This also puts quite some restrictions on the layout of the
resulting documentation. In this case ddoc is very tied to html: These
macros seem modeled directly after the DD DT DL html elements.

I tried to enhance the ddoc output over the last few weeks and it's not
ready to be released yet, but for example this is the macro structure
I've chosen for function definitions:

DDOC_FUNCTION
    DDOC_FUNCTION_HEADER_CONTAINER
        DDOC_FUNCTION_TEMPLATE_HEADER
        DDOC_FUNCTION_HEADER
            DDOC_TYPE_FUNCTION
                DDOC_FUNCTION_PREFIX
                DDOC_TYPE_MODIFIER
                DDOC_EXTRA_MODIFIER
                DDOC_TRUST
                DDOC_FUNCTION_RETURN_TYPE
                DDOC_FUNCTION_NAME
                DDOC_FUNCTION_PARAMETERS
                    DDOC_FUNCTION_LPAREN
                    DDOC_FUNCTION_PARAMETER
                        DDOC_FUNCTION_PARAMETER_STC (storage class)
                        DDOC_FUNCTION_PARAMETER_TYPE
                        DDOC_FUNCTION_PARAMETER_NAME
                        [DDOC_FUNCTION_PARAMETER_DEFAULT]
                        [DDOC_FUNCTION_COMMA]
                    [DDOC_FUNCTION_VARARGS]
                    DDOC_FUNCTION_RPAREN
            DDOC_DECLARATION_SEMICOLON
        DDOC_DITTO
            DDOC_FUNCTION_HEADER...
            DDOC_FUNCTION_TEMPLATE_HEADER...
            DDOC_TEMPLATE_HEADER
    DDOC_FUNCTION_DOC

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=,;

With more macros you can generate advanced looking documentation, for
example, this is what I currently have:
druntime docs: http://jpf.byethost10.com/druntime/doc/object.html
simple tests:
http://jpf.byethost10.com/demo/doc/ddoc/tests/simple/vars.html (druntime
2.047 in the right upper corner is still hardcoded...)

I also have xml output, but the xml ddoc file isn't complete yet
(template support is missing)
http://jpf.byethost10.com/demo_xml/ddoc/tests/simple/

And there's also a problem with phobos:in some cases the sources contain
html. In other cases there are custom macros in modules which can only
emit html(std.math, TABLE_SV, ...) and afaik you can't override module
level macros with .ddoc files?
-- 
Johannes Pfau