www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - How to create DDoc for string mixin generated functions?

reply ParticlePeter <ParticlePeter gmx.de> writes:
I am producing a bunch of functions/methods through string 
mixins. I also generated DDoc comments for those functions, in 
the hope that they would produce proper documentation, but they 
don't. So how can this be accomplished?
Nov 25 2019
parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Monday, November 25, 2019 9:25:08 AM MST ParticlePeter via Digitalmars-d-
learn wrote:

 I am producing a bunch of functions/methods through string
 mixins. I also generated DDoc comments for those functions, in
 the hope that they would produce proper documentation, but they
 don't. So how can this be accomplished?


Right now, you don't. The ddoc and function signature have to be directly in
the source code for them to be seen for ddoc generation. The closest I'm
aware of to being able to do anything along the lines of mixing in
documentation is to use template mixins, and IIRC, you not only have to have
ddoc on the mixed in symbols, but you need to put at least an empty ddoc
comment on the statement that mixes in the template. e.g. std.exception has

/++
    ...
  +/
mixin template basicExceptionCtors()
{
    /++
        Params:
            msg  = The message for the exception.
            file = The file where the exception occurred.
            line = The line number where the exception occurred.
            next = The previous exception in the chain of exceptions, if 
any.
    +/
    this(string msg, string file = __FILE__, size_t line = __LINE__,
         Throwable next = null)  nogc  safe pure nothrow
    {
        super(msg, file, line, next);
    }

    /++
        Params:
            msg  = The message for the exception.
            next = The previous exception in the chain of exceptions.
            file = The file where the exception occurred.
            line = The line number where the exception occurred.
    +/
    this(string msg, Throwable next, string file = __FILE__,
         size_t line = __LINE__)  nogc  safe pure nothrow
    {
        super(msg, file, line, next);
    }
}

and to have those constructors show up in the documentation when mixed in,
you have to do something like:

/++
    My exception class.
  +/
class MyException : Exception
{
    ///
    mixin basicExceptionCtors;
}

Without the empty ddoc comment, the documentation on the mixed in symbols
does not show up, but either way, nothing like that can currently be done
with string mixins.

There's on open bug report / enhancement request somewhere on bugzilla to
fix it so that you can document string mixins, but unless someone has done
something to fix that very recently, no one has yet to implement a fix.

- Jonathan M Davis
Nov 26 2019
parent reply ParticlePeter <ParticlePeter gmx.de> writes:
On Tuesday, 26 November 2019 at 13:02:39 UTC, Jonathan M Davis 
wrote:

 On Monday, November 25, 2019 9:25:08 AM MST ParticlePeter via 
 ...
 - Jonathan M Davis


Thanks for that thorough explanation. In may case I use the 
string mixin to forward outer struct property calls to members of 
an inner struct. I'll try to refactor the string mixin as 
template mixin.
 From top of my head I see one complication. The parameter name to 
the property would change and that means its name in the doc 
comment should change as well. Any ideas how to solve that? Or 
would it be possible only with same param name for all the 
property instantiations?
Nov 26 2019
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 26 November 2019 at 19:27:55 UTC, ParticlePeter wrote:

 In may case I use the string mixin to forward outer struct 
 property calls to members of an inner struct.


Did you try opDispatch btw? It might be simpler to implement and 
to document.


btw there might be a hacky solution to the stirng mixin thing i 
just haven't tried yet so im not sure
Nov 26 2019
parent reply ParticlePeter <ParticlePeter gmx.de> writes:
On Tuesday, 26 November 2019 at 19:41:26 UTC, Adam D. Ruppe wrote:

 On Tuesday, 26 November 2019 at 19:27:55 UTC, ParticlePeter 
 wrote:

 In may case I use the string mixin to forward outer struct 
 property calls to members of an inner struct.


 Did you try opDispatch btw? It might be simpler to implement 
 and to document.


No I didn't, I judged it being the least feasible to produce 
appropriate doc comments. How could this work?
Nov 27 2019
next sibling parent ParticlePeter <ParticlePeter gmx.de> writes:
On Wednesday, 27 November 2019 at 15:14:21 UTC, ParticlePeter 
wrote:

 On Tuesday, 26 November 2019 at 19:41:26 UTC, Adam D. Ruppe 
 wrote:

 On Tuesday, 26 November 2019 at 19:27:55 UTC, ParticlePeter 
 wrote:

 In may case I use the string mixin to forward outer struct 
 property calls to members of an inner struct.


 Did you try opDispatch btw? It might be simpler to implement 
 and to document.


 No I didn't, I judged it being the least feasible to produce 
 appropriate doc comments. How could this work?


Maybe not asked precisely enough. Its clear how op dispatch 
works, but how could I create different documentation for 
different dispatch instantiations?
Nov 28 2019
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 27 November 2019 at 15:14:21 UTC, ParticlePeter 
wrote:

 I judged it being the least feasible to produce appropriate doc 
 comments. How could this work?


Just like:

/// Forwards members to [Whatever]
auto opDispatch......

and then the documentation shows that with the link so they can 
refer to the other thing easily enough. That's what I did on my 
thing for example

http://dpldocs.info/experimental-docs/arsd.dom.ElementCollection.opDispatch.html

(possible I could make my doc gen recognize the pattern and paste 
in generated docs too, but I personally like the link enough)
Nov 28 2019
parent ParticlePeter <ParticlePeter gmx.de> writes:
On Thursday, 28 November 2019 at 14:00:56 UTC, Adam D. Ruppe 
wrote:

 On Wednesday, 27 November 2019 at 15:14:21 UTC, ParticlePeter 
 wrote:

 I judged it being the least feasible to produce appropriate 
 doc comments. How could this work?


 Just like:

 /// Forwards members to [Whatever]
 auto opDispatch......

 and then the documentation shows that with the link so they can 
 refer to the other thing easily enough. That's what I did on my 
 thing for example

 http://dpldocs.info/experimental-docs/arsd.dom.ElementCollection.opDispatch.html

 (possible I could make my doc gen recognize the pattern and 
 paste in generated docs too, but I personally like the link 
 enough)


That would not work nicely in my case. Firstly my inner structs 
are from foreign code (vulkan structs through erupted binding) 
for which I do not create documentation. Secondly, I am skipping 
some of the inner struct members.
Basically I use a template to produce the string mixin. The 
template has an VarArg list accepting inner struct member names 
to be skipped. Hence it would be better to actually create 
individual doc comments for each forwarding property 
instantiation.
Nov 28 2019