• Lars T. Kyllingstad (50/50) Apr 23 2010 I would like to propose two improvements to the DDoc system. They

"Lars T. Kyllingstad" <public kyllingen.NOSPAMnet> writes:

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