Skip to content

[Code Quality] Service.cs HandleLogWriters — XML doc comment buried inside method body becomes a no-op #859

@Christophe-Rogiers

Description

@Christophe-Rogiers

Severity: Info

File: src/Servy.Service/Service.cs, lines 1049-1077

Inside HandleLogWriters, the local function CreateWriter is preceded by what looks like an XML doc comment, but it sits inside a method body:

private void HandleLogWriters(StartOptions options)
{
    /// <summary>
    /// Helper method to create a rotating writer if the path is valid.
    /// Logs an error if the path is invalid or null/whitespace.
    /// </summary>
    /// <param name=\"path\">The file path for the log writer.</param>
    /// <returns>A <see cref=\"IStreamWriter\"/> instance or null if the path is invalid.</returns>
    IStreamWriter? CreateWriter(string? path)
    {
        ...
    }
    ...
}

C# only attaches /// doc comments to type members. Inside a method body — including before a local function — the compiler ignores the XML and emits CS1587 ("XML comment is not placed on a valid language element") on each line. The intent (a docstring on CreateWriter) is not achieved; the IDE will not pick the text up as IntelliSense, and the doc never reaches generated docs.

Suggested fix:
Replace /// with regular // comments, since local functions can't carry XML docs:

// Helper method to create a rotating writer if the path is valid.
// Logs an error if the path is invalid or null/whitespace.
// path: The file path for the log writer.
// returns: An IStreamWriter instance or null if the path is invalid.
IStreamWriter? CreateWriter(string? path)

Or, if the docstring is genuinely useful, lift CreateWriter to a private method on the class and let the XML doc work as intended.

(Compiler warnings are likely suppressed by the project; that's why this hasn't surfaced as a build break.)

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions