Freigeben über

Hyperlink your source code

  • Artikel

I just noticed that Vance Morrison  posted the source code to his latest project (Hyperaddin for Visual Studio) on CodePlex. 

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:

https://www.codeplex.com/hyperAddin/

Comments

  • Anonymous
    September 04, 2007
    primitive. really primitive. honestly? I think MS missed a huge and I do mean huge opportunity when it introduced C# to not have the source actually be code markup that was readered into source code. something like xml or html for source code you could have embedded images/diagrams in the markup - no more tab damaged ascii art. xslt to control formatting of code.  comments with bold, paramters appearing in blue, italics or whatever style you chose. refactoring would be dog simple since things like <forloop></forloop> would have controlled code constructs etc. sigh. code visualization would be cool. just render symbols based on the elemnts. branch/condition/loops. Visual Studio could have been so much more.

  • Anonymous
    September 04, 2007
    Nice thought, but the way is wrong: C# already supports structured commenting through XML comments: The <see> tag actually links to other types and members. One should utilize this already given feature instead of doing something totally new and different. ReSharper, e.g., supports this through its "Quick Documentation" (Ctrl+Q) where it displays a type's/member's XML docs in a formatted and hyperlinked tooltip window. See: http://www.jetbrains.com/resharper/features/coding_assistance.html

  • Anonymous
    September 04, 2007
    Le titre pourrait laisser penser que je ne connais pas la doc xml déjà proposée par C# , qui permet,

  • Anonymous
    September 04, 2007
    The ultimate would have the text formatting power of Donald Knuth's literate programming tools but integrated live into Visual Studio and for languages used in production.

  • Anonymous
    September 04, 2007
    The comment has been removed

  • Anonymous
    September 05, 2007
    sounds very cool, thanks for sharing.

  • Anonymous
    September 05, 2007
    um, I don't get it. /// <summary>blah blah blah<see cref="SomeOtherMethod"> </summary>

  • Anonymous
    September 05, 2007
    Why are you reinventing the wheel on this? The XML documentation in C# (along with Sandcastle) covers these bases quite well (see "see", etc). It irritates me greatly when I download source code from somebody who rolls their own documentation scheme rather than uses the built-in documentation functionality. If we really want to find the referenced bits while coding, we can right-click and choose Go To Definition or Find All References. Outside of the editor, we have Reflector and Sandcastle. I'm not sure what more you need, but rolling yet another mechanism doesn't help anyone. But I may be missing something. I tend to be critical of things that I find curiously interesting. I'll check it out.

  • Anonymous
    September 05, 2007
    It is only working for the same class methods which resides in the same source file. Am I missing something? Following is the coding I used... In Class2.cs public class Class2 { public Class2() { // // TODO: Add constructor logic here // }    public void comments()    {    } } In Class1 public class Class1 {    /// <summary>    /// code:Class2::comments blah blah    /// </summary> public Class1() { } } But above link is not navigating to the Class2 method

  • Anonymous
    September 05, 2007
    I think C# as XML would have been REALLY neat too.  It would have made all kinds of things much easier.

  • Anonymous
    September 07, 2007
    Code as xml....sounds a bit like XAML, no?

  • Anonymous
    September 09, 2007
    XAML is more of serialization format than a procedural language. XML's good for representing the the state of something and defining general workflows, but the general C syntax isn't going away any time soon. On the other hand, I tend to think that XML would make a good replacement for, say, Verilog in that you want to represent a static object (a chip) in a self-describing format with tons of parsers, transforms, and "compilation" in the form of deserialization. But on the topic of the hyperlinked code, I'm in the camp of "doesn't C# already have XML documentation for this?"