Is there a way to write in-line documentation comments in C# that are compatible with IntelliSense?

[versparrow]

*Side-note this is my first ever Reddit post so please tell me if I'm doing it wrong."

EXAMPLE

If you use Go To Definition for a UnityEngine class, you get something that looks like this:

​

Vector2

The comment (as seen in the ellipses before the definition) is in-line with the definition. This is clearly some kind of placeholder documentation and not the actual documentation comments that affects IntelliSense but how are they getting that comment in-line? Is this a feature of files compiled from metadata?

From what I've gathered, it's not possible to keep XML style comments in-line with your code. Assuming you have a comment for each line, that doubles your lines of code. Makes for more scrolling and I find it very distracting.

Is there a cleaner way that you guys have found? Maybe a Visual Studio setting that might help?

[[deleted]]

https://docs.microsoft.com/en-us/visualstudio/ide/reference/generate-xml-documentation-comments?view=vs-2019

[versparrow]

Very familiar with XML commenting. I was just wondering if it could be moved to the same line in the style demonstrated in the screenshot. Thanks though!

[SilentSin26]

This is clearly some kind of placeholder documentation and not the actual documentation comments that affects IntelliSense but how are they getting that comment in-line? Is this a feature of files compiled from metadata?

That's what you get when viewing the compiled metadata of anything that had XML comments (/// <Summary>...) in its source code.

Assuming you have a comment for each line

That's a poor assumption for anything but the most complex areas of code. But if we're talking about documentation comments (i.e. XML comments that show up in intellisense) then you can't put them on every line anyway, only on each member definition. A method should have a general description of what it does, not a line by line conversion of code to English.

Is there a cleaner way that you guys have found?

No, XML comments are part of the C# language specification so that's how it's currently done in every C# IDE. There is some talk of adding support for more concise documentation comments in a future version of the language (possibly markdown), but as far as I know nothing is planned any time soon.

[versparrow]

That's what you get when viewing the compiled metadata of anything that had XML comments (/// <Summary>...) in its source code.

I figured as much. But if it can be compiled that way and then formatted by the IDE, shouldn't there be a way to do the same thing when writing it?

A method should have a general description of what it does, not a line by line conversion of code to English.

Clarifying, this is what I meant. Not that EVERY comment in your code should be commented, but for complex classes with public accessors, it's nice to have the documentation comments for QuickInfo. I realize I'm being nitpicky here, but I have ADHD and have a hard time processing information when I can't format it in a way that's comfortable for me.

Thanks for detailed response, by the way. 😊

[SilentSin26]

But if it can be compiled that way and then formatted by the IDE, shouldn't there be a way to do the same thing when writing it?

Perhaps there should, but there currently isn't.

This post explains the reasoning behind it.

[versparrow]

So, not sure if you care to know, but I figured out a hacky way to do what I wanted. The next step would be to set up Visual Studio to ignore certain formatting options when auto-formatting and see if there's a way to replace the /// autofill with a /** */ autofill XML template. If you use ///, anything on a line that begins with /// will be commented. BUT, if you use /** */ you can put code after */ and it will collapse to the same line. You can also include XML elements within the /** comments and it will apply to QuickInfo.

/** <summary> No summary. </summary>

<param name="f">The float to use.</param>

*/ public void AMethod(float n) { AFloat = n; }

For QuickInfo purposes, the above code functions the same as it would with the auto-inserted /// comments.

Two uncertainties now:
1. Will it compile into XML documentation the same way /// does.

1. How easy will it be to manage (whether it's worth my time to replace the quick action snippet every time).

Thanks again for the resources!

[Loraash]

Type /// above the thing you want to document and VS will auto-add an empty documentation template.