I have long thought that source code comments were not enough to explain what is really going on… often you need to refer the read to other methods or areas of the code. Well, luckily for me, Vance and gang saw the same problem and went out to solve it.
Here are a few simple examples:
- You can refer to a function or type (or any other symbol), but using code:name. For example
// In this comment I wanted to talk about the code:MethodTable::Unbox method. // By Adding a code: hyperlink, readers can quickly navigate to it. Any name // that can be found using the Edit.FindSymbol (Alt-F12) can be used. If you // need to refer to an overloaded method, it is best to use an anchor (see below).
- You can generate your own URL anchors by simply putting #name in the comment somewhere. For example.
// #mytopic // // ... // Somewhere else in the file you can refer to code:#mytopic. Now readers // can quickly navigate to the #mytopic anchor.
- Without further qualification, # anchors only work within a single file. If you wish to refer to an anchor outside the current file (a common case), then you need to specify some programming symbol that is in the same file as your anchor. For example:
// I need to refer to #mytopic but it is not in the current file. But I // know that this anchor is related to the class 'MethodTable' and thus will // be in the same file as that class definition by using code:MethodTable#mytopic // I can refer to #mytopic anywhere in any code within the solution.
Check it out: