DDoc improvements
Lars T. Kyllingstad
public at kyllingen.NOSPAMnet
Fri Apr 23 01:06:56 PDT 2010
I would like to propose two improvements to the DDoc system. They
should both be possible to implement, since DDoc is built into the compiler.
1. Aliases documented as what they're aliasing
Take the following code:
void foo(T)(T t) { ... }
/// Integer foo.
alias foo!int intFoo;
The generated documentation for this is something like:
alias intFoo
Integer foo.
The problem is that this doesn't give the reader any information about
what the symbol intFoo really is, and how to use it. Since the compiler
always knows what is being aliased, it should instead generate:
void intFoo(int)
Integer foo.
2. Documentation of mixed-in stuff
Suppose I write:
mixin template DeclareFoo(T)
{
void foo(T t) { ... }
}
/// Integer foo.
mixin DeclareFoo!int;
/// Floating-point foo.
mixin DeclareFoo!double;
Here, the compiler generates no documentation at all. But again, it
knows what is being mixed in, and as such it should be able to generate
something like this:
void foo(int t)
Integer foo.
void foo(double t)
Floating-point foo.
The same should work for string mixins. In that case, one could even
imagine mixing in doc comments!
string fooDeclaration(string type)
{
string typeName = (type == "int" ? "Integer" : "Unknown");
return "
/// "~typeName~" foo.
void foo("~type~" t) { ... }";
}
mixin(fooDeclaration("int"));
I think both of the above proposals would be extremely useful features.
I mean, a major point of metaprogramming is to automatically generate
code, so you don't have to write it over and over again---not to mention
the fact that having just one version of the code in one place means a
lot less maintenance. But if you can't document your generated code,
then it suddenly is a less attractive prospect, at least if you want
others to use it.
-Lars
More information about the Digitalmars-d
mailing list