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?

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

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?

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

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?

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?

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)

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.