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
