Improving ddoc
Rikki Cattermole via Digitalmars-d
digitalmars-d at puremagic.com
Wed Dec 31 16:21:16 PST 2014
On 1/01/2015 12:59 p.m., ketmar via Digitalmars-d wrote:
> On Thu, 01 Jan 2015 12:49:06 +1300
> Rikki Cattermole via Digitalmars-d <digitalmars-d at puremagic.com> wrote:
>
>> 2. Allow usage of CTFE as a macro.
>
> this what Ddoc is really should be. no need in anything other: let all
> documentation be processed by CTFE. not by per-function basis though:
> compiler must collect *all* documentation and then call one CTFE entry
> point to process it. if we gave multiple source files in the command
> line, it should collect documentation from all that source files. this
> is to allow keeping some state when processing docs.
>
> and then everything Ddoc macros does now can be written in D. and if
> someone wants markdown... he will just write a markdown processor in D,
> and BLAM! there is markdown processor, without patching the compiler.
>
> ah, and compiler source can be made simplier, as Ddoc can be removed
> altogether.
>
> it's perfect. it will solve ALL problems. it will allow people to use
> anything they like. and we already has the D interpreter to power it.
Following this, we could extend this one altogether.
AST entry points. Read only (later maybe not) full access to dmd-fe AST.
e.g.
__ast(__ASTTree tree) {
string output = "<modules>";
foreach(string name, __ASTModule theModule; tree.modules) {
string theOutput;
output ~= "<module name=\"" ~ name ~ "\">";
output ~= "<doc>";
output ~= preprocessor(theModule.comment);
output ~= "</doc>";
output ~= "</module>";
output ~= theOutput;
// __DDOC ~= theOutput;
}
__DDOC/*[0]*/ = output ~ "</modules>";
}
Multiple __ast functions is not invalid. But one per module.
One caveat of this however is that if you have these modules they would
be required to be almost 100% standalone.
Example usage with dub, is you have an independent package that supplies
a YAML output with markdown format. To do so you will want you package
as well as possibly all predecessor and successor packages to use that
format. To do so, dub could rebuild all dependencies and pass in those
extra files. And any successor packages will have it added as a
dependency and not -I'd.
This could really kill so many birds. We could even get rid of traits
and prefer __ast(Type/Symbol) to get the AST for it.
And remember how we don't know about all modules? That's the thing, with
this approach its designed to not assume it has all. But it can see them
at some point thanks to e.g. dub.
Although this is a little extreme compared to my original post...
More information about the Digitalmars-d
mailing list