Rule SA1627 (DocumentationTextMustNotBeEmpty) and Remarks Tag

May 16, 2011 at 6:06 AM

With Style Cop 4.5.14.0, rule SA1647 fires for every empty Remarks tag. Prior to 4.5.14.0, the Remarks tag has always been an optional tag. However now StyleCop is firing for every empty remarks tag.

Is this change of behavior by design?

May 16, 2011 at 6:20 AM

I have turned off rule SA1627, yet while it it not now reported in the Error List, it still appears within the Resharper Integration.

May 16, 2011 at 8:16 AM
Edited May 16, 2011 at 10:58 AM

It is result of fixing bug I reported here: http://stylecop.codeplex.com/workitem/6936

Prior to 4.5.14, SA1627 was never reported. <summary>, <content>, <param>, <typeparam>, <returns> and <value> tags are obligatory and have their own rules, so SA1627 is never fired for them. IMHO this rule was meant for optional tags like <remarks>, <example>, <permission> and <exception>. These tags are optional, but when used, they should be filled in with valid text. Empty xml doc tags are garbage and should be deleted.

Regards

May 16, 2011 at 8:23 AM

Regarding R# integration, I suppose it is a bug in StyleCop for R#

May 16, 2011 at 9:08 AM
Przemyslaw wrote:

It is result of fixing bug I reported here: http://stylecop.codeplex.com/workitem/6936

Prior to 4.5.14, SA1647 was never reported. <summary>, <content>, <param>, <typeparam>, <returns> and <value> tags are obligatory and have their own rules, so SA1647 is never fired for them. IMHO this rule was meant for optional tags like <remarks>, <example>, <permission> and <exception>. These tags are optional, but when used, they should be filled in with valid text. Empty xml doc tags are garbage and should be deleted.

Regards

In Sandcastle Help Builder, the check on non-blank remarks is by default not run. It howver a test specifically on that tag.

I suggest that tag needs to be left with the previous behaviour as when remarks need to be made, it is far easier to enter them into an empty tag.

May 16, 2011 at 10:57 AM
TATWORTH wrote:

I suggest that tag needs to be left with the previous behaviour as when remarks need to be made, it is far easier to enter them into an empty tag.

Personally, I don't find inserting tag "from scratch" to be problematic, as VS has good intellisense support for xml doc comments. But if it bothers you and other people, then maybe SA1627 could be tweaked or remarks tag could get its own rule for missing text. Then you could keep it disabled. Anyway, it's up to Andy to decide whether it is worth to introduce new rule or to tweak current one.

You can also disable SA1627 entirely to get pre 4.5.14 behavior. It was never fired, so it is an easiest way to keep "backwards compatibility".

Coordinator
May 16, 2011 at 11:07 AM

4.5.14.0 behaviour is now correct. Its a StyleCop violation to have it there and empty. Either complete the tag or remove it completely.

May 16, 2011 at 11:11 AM
TATWORTH wrote:

With Style Cop 4.5.14.0, rule SA1647 fires for every empty Remarks tag. Prior to 4.5.14.0, the Remarks tag has always been an optional tag. However now StyleCop is firing for every empty remarks tag.

Is this change of behavior by design?


I think the appropriate question now: why would you have empty remarks tag? What purpose does it serve by being there but with empty text?

May 17, 2011 at 10:39 PM
andyr wrote:

4.5.14.0 behaviour is now correct. Its a StyleCop violation to have it there and empty. Either complete the tag or remove it completely.

Thank you for the clarification.

May 18, 2011 at 3:46 PM
andyr wrote:

4.5.14.0 behaviour is now correct. Its a StyleCop violation to have it there and empty. Either complete the tag or remove it completely.

Given the integration with ReSharper, it it possible to have a R# prompt to remove them similar to the removal of the excess brackets?