Inferring doc comments for methods that have none.

  • Article

We were going over things that came up in Ander's informal chat at Tech-Ed. It was a lot of fun because it reminded me of the difference of giving a lecture versus doing a TA recitation. You got to really just chat with people and got to walk through design issues and ideas with a whiteboard behind you. It was also fun because i got to heckle him.

One of the questions that came up was whether or not C# would support default parameters ala C++. Anders mentioned that the same could be accomplished just with regular method overloading, and that if C# were to incorporate default parameters it would probably be through overloading so that you wouldn't run into the issue of binary compatibility where the default value was baked into all the callsites. When discussing it more the issue of documentation also came up. Namely one of the current drawbacks with the overloading based approach is that if you intend for the documentation to be identical over all the overloads you must manually copy it and maintain that consistency yourself.

We were talking about if this was an issue that we should address through our tools. Basically, there are a few orthogonal that come up. First, should our tools automatically infer and duplicate documentation when the user doesn't provide it. There are a few cases where this arises:

  • If you have a virtual method defined in a base type with documentation and you override it, should we automatically show you the documentation for the base type when you use it in the IDE and should we pull in that documentation when you build a web page? This seems pretty reasonable since you're expliciting stating that you were overriding the base method
  • If you implement an interface method should we show you the documentation for that when using the concrete implementation? What if you're implementing two different interfaces that have the same method signature and both have documentation? (this probably isn't a big deal due to explicit interface implementation)
  • If you have an overload and one of the overloads has documentation should we show you that? What if there's an overload and method implemented? Also, how do you deal with documenting the difference in parameters?

An alternative approach would be a system where you used code ref's to explicitly state that you wanted the documentation copied over. For example if you had:

 /// <usedoc cref="M:Foo.Bar(System.Int32)"/>

This would require the user to place this declaration on all places where you'd want the documentation copied to. However, it would solve the problem of forcing you to keep documentation up to date across all the sites. Instead of that you could do something akin to attributes where you'd state with the initial documentation that you wanted it used on overloads or implementations. Of course, with both approaches it's not clear how you'd deal with the differences in the parameter list.  Would you place the documentation on the method with the least parameters and then document each new parameter that showed up on the overloads?  Would you document the method with the most parameters and then just ignore the parameters that were left off on the overloads with fewer?  What if you had the following

        public void Overload(string s) { }

        public void Overload(string s, int i) { }

        public void Overload(string s, bool b) { }

It's not clear how any heuristic would work if you placed documentation on only one of them but wanted some common component to all three.

If you're looking for this kind of support, could you give us examples of where you would have found it useful and if you'd prefer an automatic inference, or a declarative based approach. The automatic inference has the benefit of requiring you to do no work, but it has the potential to get things wrong. The declarative model has the benefit of always doing in right, but requiring an update to the language specification.

For the IDE we'd either use the heuristics outlined above or we'd follow teh explicit declarations to find the right documentation to show. When it was found we'd display it probably with some text like "Documentation copied from 'IFoo.Bar'" so you'd know that that was happening.