Feature Request: XML documentation handling and overriding methods

When I override a method (using "override" + Intellisense instead of using the - in my opinion - less elegant Alt+Insert => override members R# feature), the XML docs of the base method will not be copied to the new method. In R# 4.0, at least I get a bubble action which offers to copy the XML doc. But this is not enough. There should be an option to auto-copy comments from the base method.

Also, it would be great to propagate changes in XML comments to inherited methods. This could work in the following way: If XML docs of the base and the overriding method are the same, and I change the XML doc in the base method, all XML docs in the overridden methods should be changed as well.

Please consider this for R# 5.0...

BTW thanks a lot for a stable, fast, and marvellous R# 4.0 release! Back in January I thought that you perhaps wouldn't make it, because your feature-to-do list in JIRA was so long... but you proved otherwise :)

Best regards,
Urs

4 comments
Comment actions Permalink

I like the Xml comment propagation idea, and it should also support pulling up changes in overrides/implementations to the Xml comments. Ideally Xml comments would support a mechanism directly for specifying how to merge/override base comments, but that is outside the control of RS.

PS: Please add Xml comment support for exceptions (auto-documenting, updating, as well as flagging obsolete ones) similar to the way Xml comments for parameters are supported.

0
Comment actions Permalink

Hello Urs,

The feature you are referring to ("override" completion) is the feature of
Visual Studio, so we cannot fix it. We have some ideas to improve things
for future versions.

As for inheriting XML comments, I don't see any value in it. ReSharper is
capable of doing this for you dynamically, so why should you do it statically?
Well, if you are going to modify comments, it's ok to copy them, but keeping
duplicate text all over the project? Why would you need this?

Probably, you can use Quick Documentation feature (ReSharper / Code menu)?
It can work on member declaration and will show inherited docs as needed.

Sincerely,
Ilya Ryzhenkov

JetBrains, Inc
http://www.jetbrains.com
"Develop with pleasure!"


IR> When I override a method (using "override" + Intellisense instead of
IR> using the - in my opinion - less elegant Alt+Insert => override
IR> members R# feature), the XML docs of the base method will not be
IR> copied to the new method. In R# 4.0, at least I get a bubble action
IR> which offers to copy the XML doc. But this is not enough. There
IR> should be an option to auto-copy comments from the base method.
IR>
IR> Also, it would be great to propagate changes in XML comments to
IR> inherited methods. This could work in the following way: If XML docs
IR> of the base and the overriding method are the same, and I change the
IR> XML doc in the base method, all XML docs in the overridden methods
IR> should be changed as well.
IR>
IR> Please consider this for R# 5.0...
IR>
IR> BTW thanks a lot for a stable, fast, and marvellous R# 4.0 release!
IR> Back in January I thought that you perhaps wouldn't make it, because
IR> your feature-to-do list in JIRA was so long... but you proved
IR> otherwise :)
IR>
IR> Best regards,
IR> Urs


0
Comment actions Permalink

The reason propagation (up and down) is important is that maintaining/updating comments is important. It is very often the case that in implementing something, it becomes obvious that the comments could be corrected/updated. There should be a simple mechanism to automatically use the documentation from the higher declaration (encapsulation), but at the same time if a change is made to an "inherited" comment, there should be an automatic prompt to propagate the change upwards and sideways (similar to how "Find usages" asks about finding usages for the higher level instance).

Ideally there would be an Xml tag to indicate whether a comment should be propagated automatically or not, but that is beyond RS.

But for now, with C# lacking first-level specification support, quality & maintainable code requires a lot of information be placed in Xml comments, and it would be a good selling point if RS provided first-class support for Xml comments.

0
Comment actions Permalink

As for inheriting XML comments, I don't see any value in it. ReSharper is
capable of doing this for you dynamically, so why should you do it statically?
Well, if you are going to modify comments, it's ok to copy them, but keeping
duplicate text all over the project? Why would you need this?


You're right, R# Intellisense shows comments from base method dynamically, which of course is very good for the developer. However, there are some problems with it:

  • If reading through code, people expect to have the relevant comment right at the top of the method. They don't want to put the mouse over the method name and use Ctrl+Q to read the comment.

  • When making code reviews, the reviewer expects to see the comment at the top of the method and he will complain if it is not present. People who make code reviews are rather conservative and they will not be happy if you tell them "you have to install R# and use Ctrl+Q on every method to see the comment".

  • If I use tools such as NDoc, which pull XML comments from code, they don't care about R# dynamic capabilities. They won't show the comments of inherited methods.


For these reasons, yes, I would prefer to have the comments statically copied to the methods, altough they introduce some level of redundancy.

0

Please sign in to leave a comment.