Skip to content

Replace TBD XML doc placeholders in UDP IO files#8089

Open
MattKotsenas wants to merge 5 commits intoakkadotnet:devfrom
MattKotsenas:docs/io-udp
Open

Replace TBD XML doc placeholders in UDP IO files#8089
MattKotsenas wants to merge 5 commits intoakkadotnet:devfrom
MattKotsenas:docs/io-udp

Conversation

@MattKotsenas
Copy link
Contributor

Partial fix for #3435, contributes to #647.

Changes

Document all TBD XML doc blocks in the UDP-related IO files:
UdpConnection, UdpListener, UdpSender, UdpConnectedManager, UdpManager, and UdpSettings.

Doc-only change - no behavioral modifications.

Checklist

Document all TBD XML doc blocks in the UDP-related IO files:
UdpConnection, UdpListener, UdpSender, UdpConnectedManager,
UdpManager, and UdpSettings.

Doc-only change - no behavioral modifications.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy link
Member

@Aaronontheweb Aaronontheweb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good minus a few guidelines about not XML-DOCing overridden base class methods

}

/// <summary>
/// TBD
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably don't need any XML-DOCs at all for this - the natural inheritdoc from the base class should be sufficient.

/// </summary>
/// <param name="message">TBD</param>
/// <returns>TBD</returns>
/// <param name="message">The incoming message.</param>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as my comment on PostStop

@MattKotsenas
Copy link
Contributor Author

My bad, will fix!

@Aaronontheweb
Copy link
Member

My bad, will fix!

All good, it's tricky - if you're using LLMs to do this you'll want to add something to the prompt like this:

Replace all TBD XML-DOC comments with a meaningful, helpful comment that explains what the interface / class / method does without merely repeating what can be obviously inferred from the variable names. If this class / interface / member inherits or implements a base type that already has a substantive XML-DOC declared, simply delete the existing XML-DOC so the base types' one gets inherited automatically.

@MattKotsenas
Copy link
Contributor Author

Do you want a delete, or do you want an explicit ?

@Aaronontheweb
Copy link
Member

I'd delete the XML-DOC comment - correct me if I'm wrong, but the child classes / implementations will inherit the base types comments in intellisense, right?

@MattKotsenas
Copy link
Contributor Author

I just double checked and yes, if you have nothing, Intellisense does automatically pick up the base type's xmldoc.

Convention on my team is always to use <inheritdoc/> so it's clear that's the intention versus looking like "you forgot", but I'm OK with omission as well. Making changes and doing a pass through PRs now.

Remove xmldocs in derived types where the base type already has good
xmldocs.
@Aaronontheweb
Copy link
Member

Convention on my team is always to use so it's clear that's the intention versus looking like "you forgot", but I'm OK with omission as well.

that's a good point, maybe it's better that we do that then as a signal to other contributors that "this is covered already"

@MattKotsenas
Copy link
Contributor Author

@Aaronontheweb, updated (with explicit inheritdoc). Ready for another review. Double checking the other open PRs under my name now.

Copy link
Member

@Aaronontheweb Aaronontheweb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants