www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDoc and private members / mixins / UDAs

reply "Stefan Frijters" <sfrijters gmail.com> writes:
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
Jun 25 2014
parent reply "Mathias LANG" <perso.mathias.lang gmail.com> writes:
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
Jun 25 2014
parent reply "Stefan Frijters" <sfrijters gmail.com> writes:
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
Jun 26 2014
parent "bearophile" <bearophileHUGS lycos.com> writes:
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
Jun 26 2014