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