Skip to content

C# xml documentation uses wrong code block type #1934

Open
@mqudsi

Description

@mqudsi

Not using the template because this isn't a runtime bug but rather a code quality bug

(Some of) the generated SDKs are using the wrong type of code block in the XML doc comments; specifically, in many cases the <code>Foo</code> tag is used where <c>Foo</c> should have been used instead.

The <code /> block actually generates the equivalent of a <pre /> tag (the contents are displayed monospaced, but on their own line) whereas the <c /> tag generates comments that monospace the tag's contents but render it inline with everything else.

This results in overly-long and difficult-to-read intellisense hints; for example, this is how an SQS intellisense popup appears (latest 3.7.1.32 SDK):

image

Here, all the monospaced content in the popup should have actually been presented inline (including the last example of a serialized list that currently takes up two lines).

Additionally (but separately), I believe that the documentation should either use <para /> for each paragraph or hard line breaks should be translated as <br/><br/> so that the popup doesn't look like one metric ton of text without any breaks.


This is a 🐛 bug-report

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationThis is a problem with documentation.module/sdk-corep3This is a minor priority issue

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions