Skip to content
This repository was archived by the owner on Jan 12, 2024. It is now read-only.

Use the XML exception tag in doc comments (C#) #732

Merged
merged 7 commits into from
Nov 24, 2020

Conversation

kevinhartman
Copy link
Contributor

Adds proper XML tags for any exceptions previously mentioned within the summary tag.

Currently, this is only done for C# projects, since most of the F# code uses implicit summary tags.

Ref #699

@bamarsha bamarsha self-requested a review November 11, 2020 01:38
@bamarsha bamarsha self-assigned this Nov 11, 2020
Copy link
Contributor

@bamarsha bamarsha left a comment

Choose a reason for hiding this comment

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

Thanks for doing this! It's much easier to see which exceptions a function throws now. :)

@kevinhartman
Copy link
Contributor Author

kevinhartman commented Nov 15, 2020

A few TODOs prior to merge:

  • Remove "Thrown if" prefix from exception tag descriptions. Otherwise, generated documentation might be redundant (e.g. DocFX will put these descriptions inside column entitled "Conditions").
  • Add paramref tags for all parameter references in exception descriptions.
  • Combine exception tags with the same cref (approach TBD). (see discussion)
  • Add see tags for code references to exception tag descriptions.

@kevinhartman
Copy link
Contributor Author

This one is ready for another look @SamarSha

Thanks for all of the great discussion so far!

Co-authored-by: Sarah Marshall <33814365+samarsha@users.noreply.github.com>
Copy link
Contributor

@bamarsha bamarsha left a comment

Choose a reason for hiding this comment

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

Looks great! Thanks again for working on this!

@bamarsha
Copy link
Contributor

/azp run

@azure-pipelines
Copy link

Azure Pipelines successfully started running 2 pipeline(s).

@github-actions github-actions bot merged commit 572fddf into microsoft:main Nov 24, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants