FeatureRequest: Support XML Comments on local methods

[YairHalberstadt]

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. As such I like to use XML comments. I will document information relating to contracts, usages of the parameters, return type, etc.

However 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. Also, tooling can not auto-generate empty XML comments for the user to fill in.

Whilst these can't be used for Documentation (as local methods are private) the same is true for private methods, which do allow XML comments.

(This issue has been moved from dotnet/csharplang#2110)

[CyrusNajmabadi]

Note: i think this would be fine to support as a pure tooling-only feature (i.e. without changing the language). It would just be about connecting the codepaths in the compiler/IDE so that doc-comments (which are already parsed) on locals/local-functions properly light-up.

[alrz]

We could support a stripped down doc comment /// comments.. on any locals, function or otherwise, to show up in autocomplete list. I don't think xml tags would be absolutely needed here and IMO <summary> (when used alone) is just extra noise.

Furthermore, it'd would be nice to support that for other symbols as well.. and while we're at it, add some markdown support so doc comments don't poke you in the eye every time you take a glance at a well documented code.

[jnm2]

markdown support

/cc @sharwell

[sharwell]

@alrz See https://gist.github.com/sharwell/ab7a6ccab745c7e0a5b8662104e79735

[alrz]

That is a great starting point. It's interesting to see some of choices that Rust made.

Sections are markdown headers, parameters are bullet points with backtick for names,

/// Returns a person with the name given them
///
/// # Arguments
///
/// * `name` - A string slice that holds the name of the person
///
/// # Example
///
/// ```
/// // You can have rust code between fences inside the comments
/// // If you pass --test to Rustdoc, it will even test it for you!
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person

/// Returns a new Flaker based on the specified identifier
///
/// # Arguments
///
/// * `identifier` - A 6 byte vec that provides some arbitrary identification.
///
/// # Remarks
///
/// This is a convenience function that converts the `identifier` `vec` into
/// a 6 byte array. Where possible, prefer the array and use `new`.
///
/// *Note*: This also assumes the `flaker` is being created on a little endian CPU. 
pub fn new_from_identifier(identifier: Vec) -> Flaker

The rustdoc tool is used to generate user-friendly documentations, so these are nearly the same markdown for the output.

[CyrusNajmabadi]

@alrz I think any discussion of stripped/trimmed down doc comments should be another issue. For example, we already have dotnet/csharplang#878 tracking something similar.

This issue is purely about expanding the allowed set of doc-comment locations to include locals as well.

[alrz]

That's not the only thread about this stuff. It was the first time I heard that the team is actually interested to invest in this area. perhaps we should have a "champion" issue for the feature so the discussion takes place on a single GitHub thread.

[CyrusNajmabadi]

@alrz They're entirely different features. For example, this PR (imo) is simply about tooling updates, without any language changes at all. it would just be about the IDE registering these comments and displaying them, instead of dropping them on the floor. It would be entirely a dotnet/roslyn issue. On the other hand, expanding/changing what can go in a doc-comment is very much a language change belonging in dotnet/csharplang, and would require a vastly different process and effort to even bring that to the table.

Note that while these are complimentary activities, they're also orthogonal. Lighting up doc-comments for locals can happen independently. If/when the language ever decides that markdown/etc. are supported, then that would just naturally come to locals as well.

[alrz]

They're entirely different features. For example, this PR (imo) is simply about tooling updates, without any language changes at all.

doc comments are a part of language specification and the compiler is responsible to parse code segments. So I'd argue that this rather belongs to csharplang repo.

[CyrusNajmabadi]

and the compiler is responsible to parse code segments. So I'd argue that this rather belongs to csharplang repo.

Compiler is this repo :) . And the compiler is parsing these code-segments afaict. So nothing needs to change there. What needs to change is simply updating the roslyn API to just expose this info, instead of dropping it on the floor. But i could be wrong about that since i haven't debugged through.

[CyrusNajmabadi]

Oh... i do suppose on issue woudl be that if hte language doesn't specifically allow doc-comments here, that hte parser might err/warn. So you'd need that to stop happening. Which might be a language change. Objection withdrawn.

[YairHalberstadt]

In conclusion, where does this issue belong?

[sharwell]

Here is what the specification says about the placement of documentation comments:

They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method) that they annotate.

🔗 https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md

If 'member' can be interpreted to include local functions, then the issue belongs here. If 'member' does not include local functions, then the language specification would need to be updated and the issue probably belongs in dotnet/csharplang.

Requesting interpretation from @dotnet/csharplangdesign, and if they determine that the issue needs to move one of the maintainers can use a GitHub feature to move the issue.

[sharwell]

@gafter @jaredpar We would like to provide editor support for XML documentation comments on local functions. These comments would not be included in the XML file produced during a build. Can you provide an interpretation of the C# language per #32061 (comment) to determine whether this is allowed?

[AlekseyTs]

CC @agocke

[agocke]

The language does not allow doc-comments on local functions. (A local function is not a member)

[gafter]

Reopening dotnet/csharplang#2110 and championing it. We would not make this compiler change without a corresponding language change.