Code fix: SA1600 (ElementsMustBeDocumented)

[sharwell]

Implement a code fix for #120.

In general the code fix would create the necessary XML elements in a new documentation comment, but not fill in the details. However, for certain cases we can fill in these details. For example:

• The <summary> element for constructors and finalizers can be created according to SA1642 and SA1643.

• If the member needing documentation overrides or implements a member from a base class or interface, the content can be simplified to just <inheritdoc/>.

• If the member returns a Task, the <returns> element should read as follows (note we may use different wording):

  A <see cre="Task"/> representing the result of the asynchronous operation.
  

[oatkins]

Rusult!

[sharwell]

@oatkins 😑

[jimmymain]

Hi,
I think sometimes the details can be filled in.
In the case of a properly named property it would be helpful.

public string VogonConstructorFleets { get; set; }

Could quite easily be documented as:

/// <summary>
/// Gets or sets the vogon constructor fleets
/// </summary>

I think there is value in this, particularly in the case of correctly named properties.
It's a real time saver. I would be happy to take a stab at implementing it.

thoughts?

[sharwell]

@jimmymain It was my impression that several people working on this find automatically-generated documentation wrong (or useless) more frequently than it is correct (or useful). Right now I can't find the conversation I was thinking of. While they obviously have good intentions, I'm definitely not a fan of the behavior of tools like GhostDoc.

That said, please keep the following in mind:

1. Feel free to create a proposal describing specific behavior you had in mind.

2. You can always implement a code fix for SA1600 separately from this project, and install it in the same project(s) where you use StyleCop Analyzers. For example, the InheritdocCodeFixProvider in this project handles CS1591 warnings, which are not produced by this project. Anyone who finds it useful can install and use it.

   📝 While I would likely vote against adding this behavior directly to the StyleCopAnalyzers repository, I would not have any objection to creating an additional repository in the DotNetAnalyzers organization aiming to provide more comprehensive documentation generation features.

[jimmymain]

On the whole, I agree, though my feeling is that my case for properties is pretty strong.
I will implement a fix separately and post a link to it.

[pdelvo]

The documentation rules are there for a reason. The developer should write documentation that helps someone who reads the code to better understand it. Auto generated documentation for properties do not provide any value at all and the only effect it has is that it suppresses the diagnostic. This defeats the purpose.

[jimmymain]

Hi,

I understand and appreciate your point of view.
There are however a lot of cases where simple POCO objects are used. The
code fix would save time as the properties are self documenting.

There should then be a convenient way of suppressing the analysis for only
these POCO instances - which I also don't think is practical.

On Thu, 12 Nov 2015 at 13:06 Dennis Fischer [email protected]
wrote:

The documentation rules are there for a reason. The developer should write
documentation that helps someone who reads the code to better understand
it. Auto generated documentation for properties do not provide any value at
all and the only effect it has is that it suppresses the diagnostic. This
defeats the purpose.

—
Reply to this email directly or view it on GitHub
#764 (comment)
.

[jimmymain]

I have added a github project that documents properties and methods.
It seems to be working pretty well, for anyone that does want their documentation generated for those POCO classes.

https://github.com/jimmymain/Documentation.Analyzers

Regards
Craig.

[chriswbarrett]

Hi,

From the thread it looks like this hasn't been fixed. Would you accept fixes for this if I worked on it? This is an important CodeFix and I'd like to get it working

Cheers
Chris

[jimmymain]

@chrisahhh Perhaps try my code fixes: it's had a few thousand downloads, nobody has ever added any suggestions or bugs, so give it a whirl, and let me know if anything can be improved.