Allowing not generating "content" xml comment

[fredericDelaporte]

Async generator generates partial classes with a "content" xml comment, like this:

/// <content>
/// Contains generated async methods
/// </content>
public partial interface ICollectionPersister

In some tools (JetBrains Rider) under some circumstances (when the original class has non standard xml comment, such as using <para /> for splitting paragraph instead of <para>someText</para>), the intellisens show the async content comment instead of the original class comment. Removing it allow to see the original comment again.

If there is no value in having this content comment as a xml comment, maybe switching it to a simple comment would be better. In its current form it may interfere with documentation tooling.

// Contains generated async methods
public partial interface ICollectionPersister

[maca88]

I followed the recommendation from StyleCop, but if some tools have problems with it, will add an option to override the default comment.

[fredericDelaporte]

Well, if this is standard recommendation, we then should instead fix the xml comment non standard syntax which seems to trigger the trouble. (Usage of <para /> in that case.) So why not closing this issue.

[maca88]

This is just a recommentation from StyleCop, the content tag is not on the microsoft list of recommended tags, it is something that StyleCop invented. Sadly I didn't found any offical recommendation about commenting generated files, it seems that there is none. What I found, is that their tool Xsd.exe adds an empty remarks tag on each generated type. In order to satisfy everyone's needs, I will add an option to replace the default comment with a custom one or to not add a comment at all.

[maca88]

From now on, the generator will not add any documentation comment to the generated types by default, comments on partial types will be removed and for new types are just copied. The only comment that the generator will add is the <auto-generated> comment on the top of the file as it seems to be a de facto standard used by many popular generators like: xsd2code, xsd.exe, T4MVC, EF DbContext generator... For achieving the same result as before the addOrReplacePartialTypeComments option must be set (example for NHibernate project) There is also the addOrReplaceNewTypeComments option for adding or replacing comments for new types, so if a simple comment is desired to be added to all generated types the following settings should be used:

documentationComments:
  addOrReplacePartialTypeComments:
  - all: true
    content: |
      // Contains generated async methods
  addOrReplaceNewTypeComments:
  - all: true
    content: |
      // Contains generated async methods