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

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

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

Stefan Frijters:

> 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?

You can state in that GitHub thread that you could use that feature. There are many stalled nice enhancements in GitHub.

Bye,
bearophile