Inferring doc comments for methods that have none.
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.
Comments
Anonymous
August 01, 2004
The comment has been removedAnonymous
August 01, 2004
The comment has been removedAnonymous
August 01, 2004
The comment has been removedAnonymous
August 02, 2004
What I would like was to get the documentation out of the source code, entirely. I think a Documentation Project would be a better idea. This project should be able to read from source code and assemblies, provide nice editors to write the documentation in, which handtyped, commented xml is not.
The project should know exactly what is documented and not, and provide an easy picklist to chose the next item to document from. When documented things are renamed, it should provide a list of things which was documented, but now is not. Perhaps guess what it was renamed to and let the user confirm.
I think this would give us a better documentation tool while keeping the code cleaner and more readable.Anonymous
August 02, 2004
If you look at Javadoc, they have a system for inheriting comments that allows for partial inheritance. They don't allow the generic "usedoc" directive that you suggested, though I like it. We're having to write knockoffs of .net controls to build a custom theme within our application, and mostly all the documentation should just be a copy of the original control. Another reason the usedoc directive is good is that it indicates that a concious decision has been made about providing documentation - not that it has simply been forgotten.
BTW, nDoc supports an extension for building the overload summary. You just specify an <overlaods> tag on the first version...Anonymous
August 02, 2004
don't like usedoc idea - like more the potential of auto-generated comments. For instance - you override a function, or implement a function - and you go /// above it. Not just does the XML appear, but the comments from the base function. If you choose, you can then go and modify them if you want. This seems to be a very simple solution that solves all the wants imho.Anonymous
August 02, 2004
At present, NDoc obtains the summary info for type members with no documentation from their declaring type (if any). It also provides for an <overloads> tag which can be placed on any member of an overload 'group'; this tag provides documentation for the overloads list page in MS SDK-style documentation.
More info on the tags supported by the current NDoc version can be obtained from the NDoc Users Guide at http://ndoc.sourceforge.net/usersguide.html
NDoc will be introducing a new documentation inheritance mechanism in the next planned version (that is, after 1.3 which is currently in beta). We have a prototype version of it, and it appears to be working well…
Default Inheritance Process.
--------------------------------
The search path for inherited docs will be considerably more comprehensive as described below,
1. If the member is part of an overload set, the <overloads> tag.
2. Base Member.
3. Interfaces that this member implements.
4. Current Member <Description> Attribute.
5. Base Member <Description> Attribute.
then repeat the following up through inheritance chain
6. If the member is part of an overload set, the <overloads> tag.
7. Base Member.
8. Base Member <Description> Attribute.
Notes:
• Interfaces will be searched in the order they are declared, starting with those explicitly declared on the current type and then up the inheritance chain.
• DescriptionAttribute searching will be conditional on a global switch.
• <param> and <value> tags will be inherited if possible. <param> tags will be matched by name attribute; if the overloads use consistent for parameter, then the user can effectively use just the expanded <overloads> tag format for documenting all parameters in an overload 'group'.
• Other 'top-level' tags will not be inherited unless explicitly requested using the <inheritdoc> tag (see below)
New Documentation Tag <inheritdoc/>.
--------------------------------------------
This tag give users the ability to override the NDoc default process, or apply it to members that would not normally use it.
There are two main scenarios for using this tag.
* Stand-alone
The <inheritdoc/> tag can be used on its own to force document inheritance. This is must be for overridden virtual members and explicitly states that the user wants to inherit docs and hasn't just forgotten about them! All eligible documentation will be inherited. Note that this tag also has the advantage of suppressing compiler warnings of missing docs…
* Within a top-level tag
If <inheritdoc/> is used within a top-level tag such as <summary>, only documentation of that type will be inherited. If the top-level tag contains documentation, the inherited documentation will be inserted at the location indicated by <inheritdoc/> tag.
The tag can include an optional cref attribute. This attribute overrides the standard search path to allow documentation inheritance from a user-specified location.Anonymous
August 02, 2004
Darren: The issue I have with your solution is that it forced the developer to then keep the doc comments in sync during development time. If you change the base doc comment you then need to update everyone that inherits it.
Does that make sense?Anonymous
August 02, 2004
The comment has been removedAnonymous
August 03, 2004
Cyrus - I thought of that, but I'm not sure I agree. [When I say "not sure" here, I actually mean it - I'm in two minds... don't know what way I want to go]. There are two things:
a] I want nice up to date and easy comments on things, and PRESENT comments
b] I want comments to be clear and explain the INTENT of the item, not the specifics.
Now, it seems to me, that if we went letter of the law, we'd actually require CHANGING the comments on things - because if we have overridden a function - it should be important to know WHY we overrode it.
eg:
> class object:
> {
> /// <summary>
> /// this provides a representation of the class as a string
> // </summary>
> public string ToString() {...}
> }
> class Currency
> {
> /// <summary>
> /// By default, we just format the currency according to the default
> /// environment settings - so this likely to return something like "$24.00",
> /// but remember - it's not guaranteed to return that format!
> // </summary>
> public string ToString()
> {...}
Even with overloads, which are a little more homogenous, because you are mostly just simulating default parameters, or allowing it to work with different types - something in me is saying that the comment should explain what happens if we leave out that parameter - or mention the type that this overload works on.
That was why I saw my soln as a middle of the road. When you first build it - at least you get SOME comment (for the lazy among us) - and for those things where it's incredibly obvious, or fairly simple, people wouldn't bother changing it - but in most cases you're encouraged to make a small tweak - add a remark or something... and from then on the comment stands on it's own.
Also, thinking about it, I have a lot of feet in the "Design-by-contract" school - so I'm very very unlikely to be changing the comment or signature of a base function!
All that said - for overloads especially, not so much for overrides, it would be very nice to have the comments just in one place!Anonymous
August 03, 2004
Thomas Eyde: I like the way you're thinking. "able to read from source code and assemblies, provide nice editors to write the documentation in, which handtyped, commented xml is not."
You propose a documentation project, but, depending on the size of the solution, a programmer might want to document in each source file, or all of project in a single documentation file, or all of the solution in a single documentation file.
---
Cyrus, here's another idea. Currently Visual Studio supports 2 views of a form: code and designer. What if there were 3 views: code, designer, and documentation . This way we could have a nice editor for the documentation (instead of xml comments), but the information would still be stored as xml comments in the code. It seems like this wouldn't be horribly difficult since the xml comments could be extracted and edited (like XmlSpy), and information about the methods should be available from the Intellisense info, or from the parse tree used for refactoring support. (Far from trivial, though.)Anonymous
August 03, 2004
General comment on "inferring" in general.
If you infer anything, you're likely to be wrong as often as not.
Therefore, the user needs to provide a bit of information to let you decide which of two (or several) options is their preference, on a case-by-case basis.
---
Another option:
Perhaps an <overload> ... </overload> tag would be useful. Anything within the <overload> tag would be shared among all the overloads, and the editor could maintain identical duplicates of the content of the <overload> tag for each overload implementation.
To generalize this a bit, a <shared> tag might be useful. <shared scope="overload"> would be the equivalent of the tag above. I'd love to be able to say:
<shared scope="project">Copyright 2004, XYZ ... </shared> and have that automagically copied/maintained in each code file in the project.
That's just the tip of the idea. I'm sure some brainstorming about various levels/modes of sharing would result in a lot more ideas.Anonymous
August 18, 2005
Your site is realy very interesting. http://www.bignews.comAnonymous
February 15, 2006
Barcelona Hotels ,Berlin Hotels ,Madrid Hotels ,Florence Hotels ,Orlando Hotels ,San Francisco Hotels ,Milan Hotels ,San Antonio Hotels ,Prague Hotels ,San Diego Hotels ,Venice Hotels ,Atlanta Hotels ,Dublin Hotels ,Las Vegas Hotels ,Miami Beach Hotels ,Munich Hotels ,Istanbul Hotels ,Amsterdam Hotels ,Athens Hotels ,Columbus Hotels ,Sydney Hotels ,Indianapolis Hotels ,Melbourne Hotels ,Frankfurt Hotels ,Dallas Hotels ,Washington Hotels ,Austin Hotels ,Charlotte Hotels ,Brussels Hotels ,Hamburg Hotels ,Shanghai Hotels ,Sao Paulo Hotels ,Buenos Aires Hotels,Vienna Hotels ,Portland Hotels ,Phoenix Hotels ,Cancun Hotels ,Manchester Hotels ,Birmingham Hotels ,Dubai Hotels ,Nice Hotels ,New Orleans Hotels ,Nashville Hotels ,Budapest Hotels ,Los Angeles Hotels ,Richmond Hotels ,Columbia Hotels ,San Jose Hotels ,Albuquerque Hotels ,Jacksonville Hotels ,Beijing Hotels ,Honolulu Hotels ,Cologne Hotels ,Niagara Falls Hotels ,Vancouver HotelsAnonymous
February 16, 2006
Shanghai Hotels,Vienna Hotels,Cancun Hotels,Dubai Hotels,Nashville Hotels,Richmond Hotels,Albuquerque Hotels,Honolulu Hotels,Vancouver Hotels,Seattle Hotels,Miami Hotels,Zurich Hotels,Montreal Hotels,Scottsdale Hotels,Anaheim Hotels,Naples Hotels,Singapore Hotels,Oklahoma City Hotels,Geneva Hotels,Rio De Janeiro Hotels,Puerto Vallarta Hotels,Fort Worth Hotels,Philadelphia Hotels,Colorado Springs Hotels,Fort Lauderdale Hotels,Playa Del Carmen Hotels,Moscow Hotels,Rochester Hotels,Calgary HotelsAnonymous
March 07, 2006
Be clearer, please.
http://www.ms.gov/frameset.jsp?URL=http://www.ohotels.netAnonymous
January 29, 2008
The comment has been removedAnonymous
June 08, 2009
PingBack from http://cellulitecreamsite.info/story.php?id=6882Anonymous
June 19, 2009
PingBack from http://mydebtconsolidator.info/story.php?id=12299