DDoc and private members / mixins / UDAs

[Stefan Frijters via Digitalmars-d-learn]

On Thursday, 26 June 2014 at 02:33:43 UTC, Mathias LANG wrote:
> On Wednesday, 25 June 2014 at 18:49:27 UTC, Stefan Frijters 
> wrote:
>> Let me preface this by admitting that I'm not sure I'm using 
>> the DDoc functionality properly at all, so let me know if my 
>> questions are bogus.
>>
>> Is it possible to:
>> - Add private members to documentation?
>> - Have DDoc do its thing after mixins have been handled?
>> - Access UDAs?
>>
>> To expand on the last point: in my code I currently use UDAs 
>> to annotate variables that can be set in an input file; at 
>> compile time I use __traits to find all of them and create a 
>> parser etc. for them. I would really like to be able to create 
>> a minimal documentation, which only includes all such 
>> UDA-annotated variables from all modules, so it can be used as 
>> a short manual for the end user, rather than being developer 
>> documentation. I was thinking of using a LaTeX template and 
>> using the absence or presence of the UDA to somehow insert a 
>> macro that is either just blank or actually adds the 
>> documentation.
>>
>> Any tips to achieve this in a different fashion are also 
>> appreciated.
>>
>> Kind regards,
>>
>> Stefan Frijters
>
> 1) You might be interested by ddox [1] which provides more 
> functionality and a nicer output than DDoc (actually, the 
> phobos docs are being replacd by it).
> As you can see in the example, you can filter what goes in and 
> what doesn't, as well as the minimum protection level (so you 
> can chose to put private in it).
> Note that if you have a dub-based project, you can just run 
> "dub --build=ddox" to get it working.
>
> 2) Yes for regular mixin, no for template mixins. Example:
> mixin strToSym!(moduleName!moduleName); // Template mixin
> mixin("int a = 42;");                   // regular mixin
>
> Will output (using dmd -Xfdocs.json module.d):
>    {
>     "name" : "strToSym!(\"std.traits\")",
>     "kind" : "mixin",
>     "line" : 62
>    },
>    {
>     "name" : "a",
>     "kind" : "variable",
>     "protection" : "private",
>     "file" : "CppWrapper.d-mixin-63",
>     "line" : 63,
>     "deco" : "i",
>     "init" : "42"
>    },
>
>
> 3) Nope. Again, example:
> @("ThisIsAFunction")
> void foo() {}
>
> Ouputs in the docs.json:
>    {
>     "name" : "foo",
>     "kind" : "function",
>     "protection" : "private",
>     "file" : "CppWrapper.d",
>     "line" : 66,
>     "deco" : "FZv",
>     "endline" : 66
>    },
>
>
> Hope this helps !
>
> [1]: https://github.com/rejectedsoftware/ddox

Thank you! Some comments:

1) I will check it out. It looks like it may be a bit too 
HTML-centric for my taste though.

2) Here, I meant if there is a way to have the comment included 
as well. It doesn't seem like this is the case (if there are no 
hidden switches I don't know about):

/// Comment
int a;
/// Ditto
mixin("int b;");
mixin("///Ditto\nint c;");

{
   "kind" : "module",
   "file" : "testdoc2.d",
   "members" : [
    {
     "name" : "a",
     "kind" : "variable",
     "comment" : "Comment\n",
     "line" : 2,
     "char" : 5,
     "deco" : "i"
    },
    {
     "name" : "b",
     "kind" : "variable",
     "file" : "testdoc2.d-mixin-4",
     "line" : 4,
     "char" : 5,
     "deco" : "i"
    },
    {
     "name" : "c",
     "kind" : "variable",
     "file" : "testdoc2.d-mixin-5",
     "line" : 6,
     "char" : 5,
     "deco" : "i"
    }
   ]
  },

3) That's a shame. I guess I can work around it by doing a dirty 
grep beforehand and using that information to filter the json...

Related question: I found a pull request to add 
__traits(documentation, ...)[1] which would also allow me to 
solve my problem as a workaround, does anyone know if this is 
still moving forward?

[1]: https://github.com/D-Programming-Language/dmd/pull/3531