Build 251 documentation errors

1) If you define cref in hard-coded style, then you have to follow C#
specification Appendix E. So ReSharper is right.
2) Personally, I see no reason to override XML documentation.

--
Eugene Pasynkov
Developer
JetBrains, Inc
http://www.jetbrains.com
"Develop with pleasure!"
"Patrick" <no_reply@jetbrains.com> wrote in message
news:9270705.1150607176552.JavaMail.itn@is.intellij.net...

Hi All

>

I found two things with the way Resharper (build 251) handles XML
documentation.
1) if a documentation comment contains a see reference Resharper doesn't
recognize a class if it has a T: in front of it except if it is fully
qualified so:

>

/// bla bla bla <see cref="T:NameSpace.ClassName"/>

>

will work but:

>

/// bla bla bla <see cref="T:ClassName"/>

>

won't work. Even if the documentation comment is placed inside the
definition of the class (as in my case on the constructor).

>

2) If you implement an interface or abstract class Reshaper offers to
create the stubs for the required method, which is a good thing. It also
offers to copy the documentation comments. Also a good thing. It then
proceeds to add additional spacing in the documentation comments, not so
good. Mostly my documentation comments should look like

>

///<summary>
/// Some summary
///</summary>
///<param name="parameter">Comment about parameter.</param>
/// <returns>
/// Some return value
///</returns>
.. etc.

>

But they look like

>

///<summary>
/// Some summary
///</summary>
///
///<param name="parameter">Comment about parameter.</param>
///
/// <returns>
/// Some return value
///</returns>

>

Not so nice. XML comments take up enough space as is so it would be good
to not add more (basically blank) lines to the comments.

>

Anybody else seen this aswell?

>

Regards Patrick

Hi Eugene

1) If you define cref in hard-coded style, then you
have to follow C#
specification Appendix E. So ReSharper is right.

Ah ok if that is the case then I'm obviously wrong and Resharper is right. I didn't realize it was in the C# specs like this. Thanks for correcting me.

2) Personally, I see no reason to override XML
documentation.

I override documentation for 2 reasons.
1) to make changes to the documentation. e.g. replace pieces of text or add additional elements etc. (exceptions, events)
2) to make sure that VS / Resharper pick up the XML docs for the summary and the parameters. If you don't override the docs then these are not displayed as far as I know (again I may be wrong). Not having the summaries etc. means I have to actually go into the online docs to find it. Having Resharper display them is just quicker ;)

Regards

Patrick

>> 2) Personally, I see no reason to override XML
>> documentation.

I override documentation for 2 reasons.
1) to make changes to the documentation. e.g. replace pieces of text or
add additional elements etc. (exceptions, events)
2) to make sure that VS / Resharper pick up the XML docs for the summary
and the parameters. If you don't override the docs then these are not
displayed as far as I know (again I may be wrong). Not having the
summaries etc. means I have to actually go into the online docs to find
it. Having Resharper display them is just quicker ;)

1) ReSharper will look to super-methods (in interface, or in base class) for
XML documentation
2) Usually, you use such methods through interface, so end user (of your
code) will not be able too see the overriden documentation
--
Eugene Pasynkov
Developer
JetBrains, Inc
http://www.jetbrains.com
"Develop with pleasure!"

"Eugene Pasynkov (JetBrains)" <Eugene.Pasynkov@jetbrains.com> schreef in
bericht news:e75jnj$va1$1@is.intellij.net...
>
>>> 2) Personally, I see no reason to override XML
>>> documentation.
>> I override documentation for 2 reasons.
>> 1) to make changes to the documentation. e.g. replace pieces of text or
>> add additional elements etc. (exceptions, events)
>> 2) to make sure that VS / Resharper pick up the XML docs for the summary
>> and the parameters. If you don't override the docs then these are not
>> displayed as far as I know (again I may be wrong). Not having the
>> summaries etc. means I have to actually go into the online docs to find
>> it. Having Resharper display them is just quicker ;)
>

1) ReSharper will look to super-methods (in interface, or in base class)
for XML documentation
2) Usually, you use such methods through interface, so end user (of your
code) will not be able too see the overriden documentation
--
Eugene Pasynkov
Developer
JetBrains, Inc
http://www.jetbrains.com
"Develop with pleasure!"

NDoc 2 will come with a <inheritdoc/> tag and I hope that R# will support
all NDoc tags and other NDoc extensions.

Regards,
Erwin