LINQPad seems to ignore doc comments in {assembly}.xml that aren't wrapped in a <summary> tag
I've always been irked by the fact that LINQPad never shows IntelliSense information for my own assemblies, even though the feature works fine with Newtonsoft, Npgsql etc. pp. Now I have to work intensively with some old assemblies of mine, which means I absolutely need the doc comment information but hitting F12 to decompile just in order to see this info breaks the flow. In Rider, Visual Studio and elsewhere the information is displayed just fine, as it is in ILSpy obviously or the F12 trick wouldn't work.
Hence I decided to investigate. The provisional result so far is that LINQPad shows only those doc comments that contain the <summary> tag but ignores all others.
Code to reproduce right in LINQPad itself (without the need to build and reference external assemblies):
/** this doc comment gets ignored */
const int A = 0;
/// this gets ignored as well
const int B = 0;
/** <summary> this works </summary> */
const int C = 1;
/// <summary> this works, too </summary>
const int D = 1;
// note: LINQPad needs to be set to 'C# Program' (not 'C# Statements') for local doc comments to work
void Main ()
{
(A + B + C + D).Dump(); // <- a place for hovering the mouse to see what works and what doesn't
}
So it seems that LINQPad insists on seeing the <summary> tag.
This is extremely unfortunate since only a minuscule fraction of my doc comments contains the tag. The reason is that I don't believe in polluting my finely crafted source code with reams of unreadable gunk, and I believe that duplicated information and noise like redundant, non-essential comments are just as bad as missing essential comments. If a comment that is necessary for understanding the source code is also relevant at the call site then it is moved into the doc comment, not duplicated into it. Also, I have found that the visual space allotted to something in the source code should be proportional to its importance (which is why I like C#'s properties much better than Java's wildly redundant masses of getters and setters). Last but not least I believe that doc comments must also be readable in source code so that they can be read as an organic whole with the source code itself; if not then divergence between code and doc comment is only a matter of time. As a rule the combination of source code and its contained comments is the physical manifestation of my deepening understanding of a given problem facet and its possible solutions; stuff like external documentation has more of a midwive role than anything else; only the source is eternal.
The visual impact of adding <summary> to the doc comments would be in the realm of the bearable, so I'm considering it for newly written (or newly revised) code. However, I am somewhat loath to go through year's worth of C# source just in order to sprinkle it with <summary> tags. It would be preferrable if LINQPad were able to show the doc comment information in an assembly's XML file just like Rider, ILSpy and Visual Studio can.
NB: I'm not a consultant who draws advantage from inflating source with reams of needless boilerplate and endless waffling to hide his lack of sufficiently deep understanding. I am the entire IT department and I need to get sh*tloads of stuff done, yesterday, as well as staying on top of a heterogeneous codebase comprising about a million lines of FoxPro (a dBASE dialect), C++, Delphi, PHP, SQL and - lately - Java and C#, with roughly a third having been written by other programmers who worked with us over the years. 25 years of tending to that beast on a daily basis has taught me exactly what works and what is instead a waste of time that I don't have. Among the latter things I count Microsoft's doc comment scheme. How they could come up with something so hare-brained after seeing the beauty of doc comments in Java (and e.g. PHP) is beyond me, but it is what it is.
Since we got on a history trail somehow: I've used dozens of IDEs over the years - including all Borland ones since Turbo Pascal 3.0 under CP/M 2.2 and all the Microsoft ones since Visual C++ 1.x and Visual Basic - but I never found anything that complements my working style so perfectly as LINQPad, Rider and IntelliJ do. Even the eminent BC++ 3.1 was ditched decades ago (and Delphi is somewhat of a mixed bag). In a pinch I could use other IDEs instead of Rider and IntelliJ (with a lot of griping, to be sure) but there is nothing at all that could replace LINQPad. In fact, my biggest gripe with Java is the lack of anything comparable to LINQPad, since JPad unfortunately never got very far from the starting block.
Comments
Documentation comments outside the summary tag aren't picked up by Visual Studio's tooltips, so I presume you must be using Rider as your IDE?
I'm not sure exactly what the logic should be in parsing these, and how Rider handles it. For instance, if a summary tag was missing, but other XML tags were present, such as param, remarks, exception and example, what should the tooltip display?
I could easily tell LINQPad to treat plain text content as a summary tag only if no other tags are present, but then it would fail if any formatting or x-ref tags were used such as c, code, see, cref, href, etc. Would this be acceptable?
Try the latest beta - it should handle most simple cases:
https://www.linqpad.net/linqpad7.aspx#beta
Thank you, Joe, the beta works perfectly:
What would it take to entice you to add the same fix in the LINQPad 5 branch?
Yes, I'm using Rider as my primary IDE for C# - after hammering out all the hard stuff with LINQPad, of course. Having used the VC++ side of Visual Studio ever since its inception, it was natural for me to use Visual Studio for C# as well. But there was always a lot of cursing involved, I can tell you. The second I found Rider I was out of there, and now I use Visual Studio only if it cannot be avoided.
In Rider, using doc tags (
) outside of summary sections means exploring weirdness in all its wonderful forms. So, if I need to use c, cref etc. pp. then I have to wrap the doc comment in a summary section.
However, in the overwhelming majority of cases the doc comment has no tags and only one or two lines: