Bug 14633 – DDoc: false warnings for missing parameters on template declaration

There are two cases where the ddoc compiler issues a warning for missing parameters: /** Blah Params: T = some type test = something */ template case1(T) { void case1(R)(R test) { } } ///ditto alias case2 = case1!int; In both cases `test` refers to the function parameter for the template function `case1`. The ddoc compiler current looks for function parameters and template parameters, but does not check the function parameters of a nested/eponymous function template declaration.

I think the enhancement implementation should support this a little more exhaustive test case. /** Blah Params: T = The warning for this documentation should be suppressed R = The warning for this documentation should be suppressed r = The warning for this documentation should be suppressed XT = This documentation should be warned XR = This documentation should be warned xr = This documentation should be warned */ template case1(T) { void case1(R)(R r) { } } /// ditto alias case2 = case1!int; /// ditto alias case3 = unrelated!int; template unrelated(XT) { void unrelated(XR)(XR xr) {} }

I don't agree with all the new test cases. Note that "ditto" is as if you'd copy-paste the entire comment on the new declaration. So 'unrelated' is not unrelated. It's just as related as the other parts. Which is why with the current PR there's not warning emitted for `xr` and `XT` (same as `r` and `T`.) I also don't agree that we should allow `R` (nor `XR`) to be documented on the parent. The only reason to have this pattern [explicit template with nested eponymous template] is to allow one explicit template parameter (`T`), while at the same time having overloads where the other template parameter(s) (`R`) are deduced from the regular function parameter (`r`.) Instantiating the template by specifying (and therefor documenting) both template parameters seem useless. (I don't even know what that instantiation should look like.)

(In reply to Lionello Lunesu from comment #3) > I don't agree with all the new test cases. > > Note that "ditto" is as if you'd copy-paste the entire comment on the new > declaration. So 'unrelated' is not unrelated. It's just as related as the > other parts. Which is why with the current PR there's not warning emitted > for `xr` and `XT` (same as `r` and `T`.) I didn't check the documentation result of my case. Le'ts see it. template case1(T) alias case2 = case1!int.case1(R)(R r); alias case3 = unrelated!int.unrelated(XR)(XR xr); Blah Params: T The warning for this documentation should be suppressed R The warning for this documentation should be suppressed R r The warning for this documentation should be suppressed XT This documentation should be warned XR This documentation should be warned XR xr This documentation should be warned Hmm, XT is not documented in the signatures, but others are appeared. > I also don't agree that we should allow `R` (nor `XR`) to be documented on > the parent. The only reason to have this pattern [explicit template with > nested eponymous template] is to allow one explicit template parameter > (`T`), while at the same time having overloads where the other template > parameter(s) (`R`) are deduced from the regular function parameter (`r`.) > Instantiating the template by specifying (and therefor documenting) both > template parameters seem useless. (I don't even know what that instantiation > should look like.) R and XR can be specified explicitly via the aliases case2 and case3. case2!string("a"); // R == string case3!(int[])([1,2]); // And more, currently documenting T in the following code is not warned. /** Blah Params: T = x t = y */ void foo(T)(T t) {}

(In reply to Lionello Lunesu from comment #3) > Note that "ditto" is as if you'd copy-paste the entire comment on the new > declaration. So 'unrelated' is not unrelated. It's just as related as the > other parts. Which is why with the current PR there's not warning emitted > for `xr` and `XT` (same as `r` and `T`.) `unrelated` doesn't have a ditto comment. XT can't be set through case3, so why should it be documented there? > I also don't agree that we should allow `R` (nor `XR`) to be documented on > the parent. The only reason to have this pattern [explicit template with > nested eponymous template] is to allow one explicit template parameter > (`T`), while at the same time having overloads where the other template > parameter(s) (`R`) are deduced from the regular function parameter (`r`.) > Instantiating the template by specifying (and therefor documenting) both > template parameters seem useless. What harm would documenting R/XR on the parent do? > (I don't even know what that instantiation > should look like.) ---- alias c = case1!string; c!byte(42); ----

(In reply to Kenji Hara from comment #4) > Hmm, XT is not documented in the signatures, but others are appeared. I see. You think it should warn for `XT` because it's not actually being used. That's fair, but it's not related to the issue I'm fixing here. > R and XR can be specified explicitly via the aliases case2 and case3. > > case2!string("a"); // R == string > case3!(int[])([1,2]); // > > And more, currently documenting T in the following code is not warned. > > /** > Blah > Params: > T = x > t = y > */ > void foo(T)(T t) {} I understand. I can easily add this.

(In reply to Lionello Lunesu from comment #6) > I see. You think it should warn for `XT` because it's not actually being > used. That's fair, but it's not related to the issue I'm fixing here. Finally I think for the example in comment#2: - T, R, r, XR, and xr can be documented without warning - and XT should be warned. Warning for XT is related to the issue you're fixing. you're trying to handle the case 2, and in there you should not change the current warning for XT. >> void foo(T)(T t) {} > > I understand. I can easily add this. Do you mean that T should be warned? I cannot agree with that.

(In reply to Kenji Hara from comment #7) > Do you mean that T should be warned? I cannot agree with that. No, I mean allow documenting both `R` and `T`.

(In reply to Lionello Lunesu from comment #8) > No, I mean allow documenting both `R` and `T`. OK.

Commit pushed to master at https://github.com/dlang/dmd https://github.com/dlang/dmd/commit/122bcfaa5b70165e676522f94d984c6a4f2f2187 Issue 14633: Fixed false DDoc warnings (check parent template decl)

(In reply to Lionello Lunesu from comment #1) > https://github.com/D-Programming-Language/dmd/pull/4689 With the pull request merged, can this be closed as FIXED?

Commit pushed to stable at https://github.com/dlang/dmd https://github.com/dlang/dmd/commit/122bcfaa5b70165e676522f94d984c6a4f2f2187 Issue 14633: Fixed false DDoc warnings (check parent template decl)