www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Generate documentation for mixin'd function?

reply rjframe <dlang ryanjframe.com> writes:
Hi

I'm making an API for a web service, and have a small collection of 
endpoints where I'd basically be creating copy+paste functions (a small 
enough number that this isn't really that important for this project). I 
thought I'd generate them via a mixin, but haven't seen that I can 
generate documentation for the mixin'd functions with either ddoc or ddox:

---
string GenerateSimpleEndpoint(string endpoint, string type) {
    return
        "MyServiceObj " ~ endpoint ~ "(MyServiceObj service) {\n"
      ~ "    service.addQueryType(" ~ type ~ ");\n"
      ~ "    return service;\n"
      ~ "}";
}

/** My documentation goes here. No function shows up. */
mixin(GenerateSimpleEndpoint("endp", "EndpointType.MyType"));

/+
// If I write the function instead, everything's good.
MyServiceObj endp(MyServiceObj service) {
    service.addQueryType(EndpointType.MyType);
    return service;
}
+/
---

The doc generators don't see anything created via the mixin. `dmd -X` does 
have the generated function, but its "file" is "file.d-mixin-172" rather 
than just "file.d". My guess is that this is the problem for ddoc, but ddox 
doesn't appear to use this json file so it would be a different problem.

Is this intended behaviour? Am I able to document generated functions?

Thank you for your time
--Ryan
Jun 01 2018
parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Friday, June 01, 2018 21:26:18 rjframe via Digitalmars-d-learn wrote:

 Hi

 I'm making an API for a web service, and have a small collection of
 endpoints where I'd basically be creating copy+paste functions (a small
 enough number that this isn't really that important for this project). I
 thought I'd generate them via a mixin, but haven't seen that I can
 generate documentation for the mixin'd functions with either ddoc or ddox:

 ---
 string GenerateSimpleEndpoint(string endpoint, string type) {
     return
         "MyServiceObj " ~ endpoint ~ "(MyServiceObj service) {\n"
       ~ "    service.addQueryType(" ~ type ~ ");\n"
       ~ "    return service;\n"
       ~ "}";
 }

 /** My documentation goes here. No function shows up. */
 mixin(GenerateSimpleEndpoint("endp", "EndpointType.MyType"));

 /+
 // If I write the function instead, everything's good.
 MyServiceObj endp(MyServiceObj service) {
     service.addQueryType(EndpointType.MyType);
     return service;
 }
 +/
 ---

 The doc generators don't see anything created via the mixin. `dmd -X` does
 have the generated function, but its "file" is "file.d-mixin-172" rather
 than just "file.d". My guess is that this is the problem for ddoc, but
 ddox doesn't appear to use this json file so it would be a different
 problem.

 Is this intended behaviour? Am I able to document generated functions?

 Thank you for your time
 --Ryan


It's currently possible to put ddoc on template mixins but not string
mixins:

https://issues.dlang.org/show_bug.cgi?id=2420

It was fix for template mixins with

https://issues.dlang.org/show_bug.cgi?id=648

but has yet to be fixed for string mixins.

- Jonathan M Davis
Jun 01 2018
parent rjframe <dlang ryanjframe.com> writes:
On Fri, 01 Jun 2018 22:48:41 -0600, Jonathan M Davis wrote:

 
 It's currently possible to put ddoc on template mixins but not string
 mixins:
 
 https://issues.dlang.org/show_bug.cgi?id=2420
 
 It was fix for template mixins with
 
 https://issues.dlang.org/show_bug.cgi?id=648
 
 but has yet to be fixed for string mixins.
 
 - Jonathan M Davis



Thank you.

--Ryan
Jun 02 2018