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
