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

src/Documentation/DocumentationParser/Utils.cs

@@ -406,7 +406,7 @@ internal static void WriteYamlFile(YamlNode rootNode, string rootPath, string fi
         /// If the file is not a YAML map, then its contents are blindly overwritten.
         /// </summary>
         /// <param name="map">The YAML mapping node to merge into the data in the file.</param>
-        /// <param name="fileName">The full path name of the file to read and rewrite.</param>
+        /// <param name="fileBaseName">The full path name of the file to read and rewrite.</param>
         internal static void MergeYamlFile(YamlMappingNode map, string rootPath, string fileBaseName)
         {
             var yamlReader = new YamlStream();

src/QsCompiler/CommandLineTool/Commands/Diagnose.cs

@@ -141,8 +141,8 @@ private static void PrintContentTokenization(Compilation compilation, ILogger lo
         /// If the given evaluated tree is null, queries the tree contained in the given compilation instead.
         /// If the id of a file is consistent with the one assigned to a code snippet,
         /// strips the lines of code that correspond to the wrapping defined by WrapSnippet.
-        /// Throws an ArgumentException if this is not possible because the given syntax tree is inconsistent with that wrapping.
         /// </summary>
+        /// <exception cref="ArgumentException">This is not possible because the given syntax tree is inconsistent with that wrapping.</exception>
         private static void PrintSyntaxTree(IEnumerable<QsNamespace>? evaluatedTree, Compilation compilation, ILogger logger)
         {
             evaluatedTree ??= compilation.SyntaxTree.Values;
@@ -175,8 +175,8 @@ void PrintTree(string serialization) => logger.Log(
         /// If the given evaluated tree is null, queries the tree contained in the given compilation instead.
         /// If the id of a file is consistent with the one assigned to a code snippet,
         /// strips the lines of code that correspond to the wrapping defined by WrapSnippet.
-        /// Throws an ArgumentException if this is not possible because the given syntax tree is inconsistent with that wrapping.
         /// </summary>
+        /// <exception cref="ArgumentException">This is not possible because the given syntax tree is inconsistent with that wrapping.</exception>
         private static void PrintGeneratedQs(IEnumerable<QsNamespace>? evaluatedTree, Compilation compilation, ILogger logger)
         {
             evaluatedTree ??= compilation.SyntaxTree.Values;
@@ -203,8 +203,8 @@ private static void PrintGeneratedQs(IEnumerable<QsNamespace>? evaluatedTree, Co
 
         /// <summary>
         /// Strips the namespace and callable declaration that is consistent with the wrapping defined by WrapSnippet.
-        /// Throws an ArgumentException if this is not possible because the given syntax tree is inconsistent with that wrapping.
         /// </summary>
+        /// <exception cref="ArgumentException">This is not possible because the given syntax tree is inconsistent with that wrapping.</exception>
         public static IEnumerable<QsStatement> StripSnippetWrapping(IEnumerable<QsNamespace> syntaxTree)
         {
             var incorrectWrapperException = new ArgumentException("syntax tree does not reflect the expected wrapper");

src/QsCompiler/CommandLineTool/Commands/Format.cs

@@ -70,8 +70,8 @@ public static string UpdateArrayLiterals(string fileContent)
         /// Generates formatted Q# code based on the part of the syntax tree that corresponds to each file in the given compilation.
         /// If the id of a file is consistent with the one assigned to a code snippet,
         /// strips the lines of code that correspond to the wrapping defined by WrapSnippet.
-        /// Throws an ArgumentException if this is not possible because the given syntax tree is inconsistent with that wrapping.
         /// </summary>
+        /// <exception cref="ArgumentException">This is not possible because the given syntax tree is inconsistent with that wrapping.</exception>
         private static IEnumerable<string> GenerateQsCode(Compilation compilation, string file, ILogger logger)
         {
             if (Options.IsCodeSnippet(file))

src/QsCompiler/CommandLineTool/CompilationTracker.cs

@@ -301,9 +301,9 @@ public static void OnCompilationTaskEvent(object sender, CompilationLoader.Compi
 
         /// <summary>
         /// Publishes the results to text files in the specified folder.
-        /// Throws an IOException if the specified output folder is a file path.
-        /// Throws a NotSupportedException if the path to the output folder is malformed.
         /// </summary>
+        /// <exception cref="NotSupportedException"><paramref name="outputFolder"/> is malformed.</exception>
+        /// <exception cref="IOException"><paramref name="outputFolder"/> is a file path.</exception>
         public static void PublishResults(string outputFolder)
         {
             var compilationProcessesForest = BuildCompilationTasksHierarchy();

src/QsCompiler/CommandLineTool/LoadContext.cs

@@ -151,8 +151,8 @@ public static void UnloadAll()
         /// Loads an assembly at the given location into a new context.
         /// Adds the specified fallback locations, if any,
         /// to the list of paths where the context will try to look for assemblies that could otherwise not be loaded.
-        /// Throws a FileNotFoundException if no file with the given path exists.
         /// </summary>
+        /// <exception cref="FileNotFoundException">File at <paramref name="path"/> does not exist.</exception>
         public static Assembly LoadAssembly(string path, string[]? fallbackPaths = null)
         {
             if (!File.Exists(path))

src/QsCompiler/CompilationManager/AssemblyLoader.cs

@@ -31,10 +31,10 @@ public static class AssemblyLoader
         /// Returns false if some of the content could not be loaded successfully,
         /// possibly because the referenced assembly has been compiled with an older compiler version.
         /// If onDeserializationException is specified, invokes the given action on any exception thrown during deserialization.
-        /// Throws an ArgumentException if the URI is not an absolute file URI.
-        /// Throws a FileNotFoundException if no file with the given name exists.
         /// Throws the corresponding exceptions if the information cannot be extracted.
         /// </summary>
+        /// <exception cref="FileNotFoundException"><paramref name="asm"/> does not exist.</exception>
+        /// <exception cref="ArgumentException"><paramref name="asm"/> is not an absolute file URI.</exception>
         public static bool LoadReferencedAssembly(Uri asm, out References.Headers headers, bool ignoreDllResources = false, Action<Exception>? onDeserializationException = null)
         {
             var id = CompilationUnitManager.GetFileId(asm);
@@ -62,8 +62,8 @@ public static bool LoadReferencedAssembly(Uri asm, out References.Headers header
         /// possibly because the referenced assembly has been compiled with an older compiler version.
         /// Catches any exception throw upon loading the compilation, and invokes onException with it if such an action has been specified.
         /// Sets the out parameter to null if an exception occurred during loading.
-        /// Throws a FileNotFoundException if no file with the given name exists.
         /// </summary>
+        /// <exception cref="FileNotFoundException"><paramref name="asmPath"/> does not exist.</exception>
         public static bool LoadReferencedAssembly(
             string asmPath,
             [NotNullWhen(true)] out QsCompilation? compilation,

src/QsCompiler/CompilationManager/CompilationUnit.cs

@@ -165,8 +165,8 @@ static QsDeclarationAttribute Renamed(QsQualifiedName originalName, Position dec
         /// Combines the current references with the given references, and verifies that there are no conflicts.
         /// Calls the given Action onError with suitable diagnostics if two or more references conflict,
         /// i.e. if two or more references contain a declaration with the same fully qualified name.
-        /// Throws an ArgumentException if the given set shares references with the current one.
         /// </summary>
+        /// <exception cref="ArgumentException">The given set (<paramref name="other"/>) shares references with the current one.</exception>
         internal References CombineWith(References other, Action<ErrorCode, string[]>? onError = null)
         {
             if (this.Declarations.Keys.Intersect(other.Declarations.Keys).Any())
@@ -406,8 +406,8 @@ internal void UnregisterDependentLock(ReaderWriterLockSlim depLock)
 
         /// <summary>
         /// Enters a read-lock, provided none of the dependent locks is set, or a compilation lock is aready held.
-        /// Throws an InvalidOperationException if any of the dependent locks is set, but the SyncRoot is not at least read-lock-held.
         /// </summary>
+        /// <exception cref="InvalidOperationException">Any of the dependent locks is set, but the SyncRoot is not at least read-lock-held.</exception>
         public void EnterReadLock()
         {
             #if DEBUG
@@ -427,8 +427,8 @@ public void EnterReadLock()
 
         /// <summary>
         /// Enters an upgradeable read-lock, provided none of the dependent locks is set, or a suitable compilation lock is aready held.
-        /// Throws an InvalidOperationException if any of the dependent locks is set, but the SyncRoot is not at least read-lock-held.
         /// </summary>
+        /// <exception cref="InvalidOperationException">Any of the dependent locks is set, but the SyncRoot is not at least read-lock-held.</exception>
         public void EnterUpgradeableReadLock()
         {
             #if DEBUG
@@ -447,8 +447,8 @@ public void EnterUpgradeableReadLock()
 
         /// <summary>
         /// Enters a write-lock, provided none of the dependent locks is set, or a suitable compilation lock is aready held.
-        /// Throws an InvalidOperationException if any of the dependent locks is set, but the SyncRoot is not at least read-lock-held.
         /// </summary>
+        /// <exception cref="InvalidOperationException">Any of the dependent locks is set, but the SyncRoot is not at least read-lock-held.</exception>
         public void EnterWriteLock()
         {
             #if DEBUG
@@ -784,8 +784,8 @@ public static ImmutableArray<QsNamespace> NewSyntaxTree(
         /// Returns the built Q# compilation reflecting the current internal state.
         /// Note that functor generation directives are *not* evaluated in the the returned compilation,
         /// and the returned compilation may contain invalid parts.
-        /// Throws an InvalidOperationException if a callable definition is listed in GlobalSymbols for which no compilation exists.
         /// </summary>
+        /// <exception cref="InvalidOperationException">A callable definition is listed in <see cref="GlobalSymbols"/> for which no compilation exists.</exception>
         public QsCompilation Build()
         {
             this.syncRoot.EnterReadLock();
@@ -848,8 +848,8 @@ public QsCompilation Build()
         /// <summary>
         /// Returns a look-up that contains the names of all namespaces and the corresponding short hand, if any,
         /// imported within a certain source file for the given namespace.
-        /// Throws an ArgumentException if no namespace with the given name exists.
         /// </summary>
+        /// <exception cref="ArgumentException">No namespace exists with name <paramref name="nsName"/>.</exception>
         public ILookup<string, (string, string?)> GetOpenDirectives(string nsName)
         {
             this.syncRoot.EnterReadLock();

src/QsCompiler/CompilationManager/CompilationUnitManager.cs

@@ -152,7 +152,7 @@ public void Dispose()
         /// <summary>
         /// Converts a URI into the file ID used during compilation if the URI is an absolute file URI.
         /// </summary>
-        /// <exception cref="ArgumentException">Thrown if the URI is not an absolute file URI.</exception>
+        /// <exception cref="ArgumentException"><paramref name="uri"/> is not an absolute file URI.</exception>
         public static string GetFileId(Uri uri)
         {
             if (!uri.IsAbsoluteUri || !uri.IsFile)
@@ -214,8 +214,8 @@ private void UnsubscribeFromFileManagerEvents(FileContentManager file)
         /// <summary>
         /// Initializes a FileContentManager for the given document with the given content.
         /// If an Action for publishing is given, publishes the diagnostics generated upon processing the given content.
-        /// Throws an ArgumentException if the uri of the given text document identifier is not an absolute file uri.
         /// </summary>
+        /// <exception cref="ArgumentException"><paramref name="uri"/> is not an absolute file URI.</exception>
         public static FileContentManager InitializeFileManager(
             Uri uri,
             string fileContent,
@@ -238,8 +238,8 @@ public static FileContentManager InitializeFileManager(
         /// <summary>
         /// Initializes a FileContentManager for each entry in the given dictionary of source files and their content.
         /// If an Action for publishing is given, publishes the diagnostics generated upon content processing.
-        /// Throws an ArgumentException if any of the given uris is not an absolute file uri.
         /// </summary>
+        /// <exception cref="ArgumentException">Any of the given URIs in <paramref name="files"/> is not an absolute file URI.</exception>
         public static ImmutableHashSet<FileContentManager> InitializeFileManagers(
             IDictionary<Uri, string> files,
             Action<PublishDiagnosticParams>? publishDiagnostics = null,
@@ -305,9 +305,9 @@ public Task AddOrUpdateSourceFilesAsync(ImmutableHashSet<FileContentManager> fil
 
         /// <summary>
         /// Modifies the compilation and all diagnostics to reflect the given change.
-        /// Throws a InvalidOperationException if file for which a change is given is not listed as source file.
-        /// Throws an ArgumentException if the uri of the given text document identifier is null or not an absolute file uri.
         /// </summary>
+        /// <exception cref="ArgumentException">The URI of the given text document identifier is null or not an absolute file URI.</exception>
+        /// <exception cref="InvalidOperationException">The file for which a change is given is not listed as a source file.</exception>
         public Task SourceFileDidChangeAsync(DidChangeTextDocumentParams param) =>
             this.Processing.QueueForExecutionAsync(() =>
             {
@@ -343,8 +343,8 @@ public Task SourceFileDidChangeAsync(DidChangeTextDocumentParams param) =>
         /// Called in order to process any queued changes in the file with the given URI and
         /// - if verifications are enabled - trigger a semantic check.
         /// Does not do anything if no file with the given URI is listed as source file of this compilation.
-        /// Throws an ArgumentException if the URI of the given text document identifier is null or not an absolute file URI.
         /// </summary>
+        /// <exception cref="ArgumentException"><paramref name="uri"/> is null or not an absolute file URI.</exception>
         private Task TriggerFileUpdateAsync(Uri uri)
         {
             var docKey = GetFileId(uri);
@@ -378,8 +378,8 @@ private Task TriggerFileUpdateAsync(Uri uri)
         /// publishes empty Diagnostics for that file unless publishEmptyDiagnostics is set to false,
         /// and adapts all remaining diagnostics as needed.
         /// Does nothing if no file with the given Uri is listed as source file.
-        /// Throws an ArgumentException if the uri of the given text document identifier is null or not an absolute file uri.
         /// </summary>
+        /// <exception cref="ArgumentException"><paramref name="uri"/> is null or not an absolute file URI.</exception>
         public Task TryRemoveSourceFileAsync(Uri uri, bool publishEmptyDiagnostics = true)
         {
             var docKey = GetFileId(uri);
@@ -410,8 +410,8 @@ public Task TryRemoveSourceFileAsync(Uri uri, bool publishEmptyDiagnostics = tru
         /// and adapts all remaining diagnostics as needed.
         /// Does nothing if a file with the given Uri is not listed as source file.
         /// Spawns a compilation unit wide type checking unless suppressVerification is set to true, even if no files have been removed.
-        /// Throws an ArgumentException if the uri of the given text document identifier is not an absolute file uri.
         /// </summary>
+        /// <exception cref="ArgumentException">A URI in <paramref name="files"/> is not an absolute file URI.</exception>
         public Task TryRemoveSourceFilesAsync(IEnumerable<Uri> files, bool suppressVerification = false, bool publishEmptyDiagnostics = true)
         {
             if (files.Any(uri => !uri.IsAbsoluteUri || !uri.IsFile))

src/QsCompiler/CompilationManager/ContextBuilder.cs

@@ -22,8 +22,8 @@ internal static class ContextBuilder
 
         /// <summary>
         /// Verifies that all tokens are ordered according to their range.
-        /// Throws an ArgumentException if this is not the case.
         /// </summary>
+        /// <exception cref="ArgumentException">Not all <paramref name="tokens"/> are ordered according to their range.</exception>
         internal static void VerifyTokenOrdering(IEnumerable<CodeFragment> tokens)
         {
             Position? previousEnding = null;
@@ -221,8 +221,8 @@ public static ((string, Position), (QsSpecializationKind?, Position?))? TryGetCl
         /// Returns true if the given file contains any tokens overlapping with the given fragment.
         /// The range of the tokens in the file is assumed to be relative to their start line (the index at which they are listed),
         /// whereas the range of the given fragment is assumed to be the absolute range.
-        /// Throws an ArgumentOutOfRangeException if the given range is not a valid range within file.
         /// </summary>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="range"/> is not a valid range within <paramref name="file"/>.</exception>
         internal static bool ContainsTokensOverlappingWith(this FileContentManager file, Range range)
         {
             if (!file.ContainsRange(range))
@@ -255,8 +255,8 @@ internal static bool ContainsTokensOverlappingWith(this FileContentManager file,
         /// <summary>
         /// Assuming both the current tokens and the tokens to update are sorted according to their range,
         /// merges the current and updated tokens such that the merged collection is sorted as well.
-        /// Throws a QsCompilerException if the token verification for the merged collection fails.
         /// </summary>
+        /// <exception cref="QsCompilerException">The token verification for the merged collection failed.</exception>
         internal static List<CodeFragment> MergeTokens(IEnumerable<CodeFragment> current, IEnumerable<CodeFragment> updated)
         {
             var merged = new List<CodeFragment>(0);