FeatureRequest: Support XML Comments on local methods

[YairHalberstadt]

Currently XML comments are invalid on local methods. As a result, if you add XML comments to local methods, they don't show up in intellisense.

Besides, I find it useful to document behavior of local methods, and having a fixed specification as to how to do so would be useful, rather than an ad-hoc comment system.

(Using XML comments on a local method also generates a warning in resharper that they are not placed on a valid language element, though obviously this isn't the relevant forum for that issue).

[Richiban]

I'm not really sure why you would ever want XML docs on local methods... since they're normally used for documenting the public API of your library and local methods are, by definition, not public.

Can you give us an example of where you'd like XML comments to show up? Are you using it to document the throwing of exceptions rather than comments?

[YairHalberstadt]

I'm using it to say things like what the parameters do, contracts, what it might throw, what the method does, and random comments like "Performance Critical"

I could of course use ad hoc comments to do all that, but I like the formal system of XML comments.

I will point out that XML comments are allowed on private methods, where the same arguments could apply.

[Richiban]

I know it seems that the line is very thin between private and local methods but it's the same as the difference between fields/properties and local variables, isn't it? ... still I think that local methods are small (they're inside another method!) so you can just look at it to see what it does.

[YairHalberstadt]

I don't claim it's particularly important.

It's more that if it's easy to do, I can't see any disadvantages to it, and I would find it useful. It doesn't add any complexity to the language.

[YairHalberstadt]

And yes, you can look inside the method, but you would still need a comment along the lines of \\ parameter X must be initialised before calling this method. XML docs give a formal structure for that kind of comment, and intellisense is quite helpful for that kind of thing.

[YairHalberstadt]

For anyone on the LDM, Roslyn team:

With this the sort of thing that if I were to hypothetically implement it and raise a PR, would it likely be merged, or does this still need the LDM to discuss it?

[CyrusNajmabadi]

For anyone on the LDM, Roslyn team:

With this the sort of thing that if I were to hypothetically implement it and raise a PR, would it likely be merged, or does this still need the LDM to discuss it?

Not on the LDM. However, my take on it is that this looks like this could be entirely done as a tooling change, with no need for any sort of language change. The more i think about it, the more i think it's basically entirely reasonable for any symbol (including locals) to have a doc-comment on it that can be used for tool-time help. These local doc-comments might never be emitted to a doc-file, but could still be used to inform the tooling side of things.

I would recommend closing this issue and opening a request over at dotnet/roslyn.

[YairHalberstadt]

@CyrusNajmabadi
Thanks. Will do.

[gafter]

See also #2110

I am championing this.

[DarkSystemCD]

would think the description for XML Comments be like ::

XML Comments allows the developer to better organize the code;
Annotate namespace,classes,methods,variables,local functions,[...]
the comments then are removed from the compilation which and external file could also being referenced in code;

anything else about the productivity with XML Comments are manifestations from internet,
which means the feature should be a development time resource not a product;

example of product comment

I'm not really sure why you would ever want XML docs on local methods... [...]

[dirkbaum]

I would find it to be a very helpful to be able to document local functions and have the documentation exposed in the IDE intellisense.

[Neme12]

See also #2110

I am championing this.

You linked to the same issue.