Open-XML-SDK icon indicating copy to clipboard operation
Open-XML-SDK copied to clipboard

Published 20 hours ago • verified publisher icon dotnet

Some source files use <remark> tags rather than <remarks> in their documentation comments

Open AlissaSabre opened this issue 1 year ago • 0 comments

Describe the bug Some C# source files in this repository, mostly those generated from the schema and put in generated/, use <remark> tags rather than the usual <remarks> tags in their documentation comments. As a result, some development tools that use the documentation comments or the XML documentation files fail to use the remark information.

Screenshots vscode showing the information for DocumentFormat.OpenXml.Wordprocessing.ParagraphPropertiesChange class in the file generated\DocumentFormat.OpenXml\DocumentFormat.OpenXml.Generator\DocumentFormat.OpenXml.Generator.OpenXmlGenerator\schemas_openxmlformats_org_wordprocessingml_2006_main.g.cs. (Red lines are added manually.)

before fix

To Reproduce

  1. Start vscode and open the folder for the repository.
  2. On the Explorer pane, locate the file generated\DocumentFormat.OpenXml\DocumentFormat.OpenXml.Generator\DocumentFormat.OpenXml.Generator.OpenXmlGenerator\schemas_openxmlformats_org_wordprocessingml_2006_main.g.cs and click it to open it.
  3. Scroll down to find the (partial) class definition for ParagraphPropertiesChange.
  4. Observe the documentation comment above it, then hover your mouse cursor over the identifier.

Observed behavior

  1. The documentation comment uses <remark> and </remark> tag pair.
  2. The popup shows only the summary part of the documentation comment.

Expected behavior

  1. The documentation comment uses <remarks> and </remarks> tag pair.
  2. The popup shows both summary and remark parts.

after fix

Desktop (please complete the following information):

  • OS: Windows 11
  • Office version: version 2407 build 16.0.17830.20056
  • .NET Target: .NET Framework 4.8.1
  • DocumentFormat.OpenXml Version: 3.1.0

Additional notes The major cause of this issue is a bug in the schema to C# code generator. However, there are a few files outside generated/ that use <remark>. They are:

  • src/DocumentFormat.OpenXml/Schema/Presentation/CommentPropertiesExtension.cs and
  • src/DocumentFormat.OpenXml/Schema/Wordprocessing/CustomXmlElement.cs.

AlissaSabre avatar Aug 24 '24 06:08 AlissaSabre