Merge pull request #3 from microsoft/beheim/docComments

XML format for doc comments in C# code

Author: bettinaheim

src/QsCompiler/CommandLineTool/Commands/Build.cs

@@ -54,12 +54,14 @@ public static IEnumerable<Example> UsageExamples
 
         // publicly accessible routines 
 
+        /// <summary>
         /// Builds the compilation for the Q# code or Q# snippet and referenced assemblies defined by the given options.
         /// Invokes all specified targets (dotnet core apps) with suitable TargetOptions,
         /// that in particular specify the path to the compiled binary as input and the same output folder, verbosity, and suppressed warnings as the given options.
         /// The output folder is set to the current directory if one or more targets have been specified but the output folder was left unspecified.
         /// Returns a suitable error code if one of the compilation or generation steps fails.
         /// Throws an ArgumentNullException if any of the given arguments is null.
+        /// </summary>
         public static int Run(BuildOptions options, ConsoleLogger logger)
         {
             if (options == null) throw new ArgumentNullException(nameof(options));

src/QsCompiler/CommandLineTool/Commands/Diagnose.cs

@@ -58,11 +58,12 @@ public static IEnumerable<Example> UsageExamples
             public bool PrintCompiledCode { get; set; }
         }
 
-
+        /// <summary>
         /// Logs the content of each file in the given compilation as Information using the given logger. 
         /// 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 ArgumentNullException if the given compilation is null.
+        /// </summary>
         private static void PrintFileContentInMemory(Compilation compilation, ILogger logger)
         {
             if (compilation == null) throw new ArgumentNullException(nameof(compilation));
@@ -83,10 +84,12 @@ private static void PrintFileContentInMemory(Compilation compilation, ILogger lo
             }
         }
 
+        /// <summary>
         /// Logs the tokenization of each file in the given compilation as Information using the given logger. 
         /// If the id of a file is consistent with the one assigned to a code snippet,
         /// strips the tokens that correspond to the wrapping defined by WrapSnippet.
         /// Throws an ArgumentNullException if the given compilation is null.
+        /// </summary>
         private static void PrintContentTokenization(Compilation compilation, ILogger logger)
         {
             if (compilation == null) throw new ArgumentNullException(nameof(compilation));
@@ -113,13 +116,15 @@ private static void PrintContentTokenization(Compilation compilation, ILogger lo
             }
         }
 
+        /// <summary>
         /// Logs the part of the given evaluated syntax tree that corresponds to each file 
         /// in the given compilation as Information using the given logger. 
         /// 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.  
         /// Throws an ArgumentNullException if the given compilation is null.
+        /// </summary>
         private static void PrintSyntaxTree(IEnumerable<QsNamespace> evaluatedTree, Compilation compilation, ILogger logger)
         {
             if (compilation == null) throw new ArgumentNullException(nameof(compilation));
@@ -141,13 +146,15 @@ void PrintTree(string serialization) => logger.Log(
             }
         }
 
+        /// <summary>
         /// Logs the generated Q# code for the part of the given evaluated syntax tree that corresponds to each file 
         /// in the given compilation as Information using the given logger. 
         /// 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.  
         /// Throws an ArgumentNullException if the given compilation is null.
+        /// </summary>
         private static void PrintGeneratedQs(IEnumerable<QsNamespace> evaluatedTree, Compilation compilation, ILogger logger)
         {
             if (compilation == null) throw new ArgumentNullException(nameof(compilation));
@@ -174,9 +181,11 @@ private static void PrintGeneratedQs(IEnumerable<QsNamespace> evaluatedTree, Com
 
         // publicly accessible methods
 
+        /// <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.
         /// Throws an ArgumentNullException if the given syntaxTree is null. 
+        /// </summary>
         public static IEnumerable<QsStatement> StripSnippetWrapping(IEnumerable<QsNamespace> syntaxTree)
         {
             if (syntaxTree == null) throw new ArgumentNullException(nameof(syntaxTree));
@@ -189,10 +198,12 @@ public static IEnumerable<QsStatement> StripSnippetWrapping(IEnumerable<QsNamesp
             else throw incorrectWrapperException;
         }
 
+        /// <summary>
         /// Builds the compilation for the Q# code or Q# snippet and referenced assemblies defined by the given options.
         /// Prints the data structures requested by the given options using the given logger.
         /// Returns a suitable error code if one of the compilation or generation steps fails.
         /// Throws an ArgumentNullException if any of the given arguments is null.
+        /// </summary>
         public static int Run(DiagnoseOptions options, ConsoleLogger logger)
         {
             if (options == null) throw new ArgumentNullException(nameof(options));

src/QsCompiler/CommandLineTool/Commands/Format.cs

@@ -44,21 +44,26 @@ public static IEnumerable<Example> UsageExamples
             public string OutputFolder { get; set; }
         }
 
-
+        /// <summary>
         /// Regex that matches anything within array brackets.
+        /// </summary>
         public static readonly Regex WithinArrayBrackets =
             new Regex(@"\[(?:[^\[\]]|(?<ctr>\[)|(?<-ctr>\]))*(?(ctr)(?!))\]");
 
+        /// <summary>
         /// Replaces all semicolons that occur within array brackets in the given string with commas. 
+        /// </summary>
         public static string UpdateArrayLiterals(string fileContent)
         {
             string ReplaceSemicolons(Match match) => match.Value.Replace(';', ',');
             return WithinArrayBrackets.Replace(fileContent, ReplaceSemicolons);
         }
 
 
+        /// <summary>
         /// Returns formatted Q# code for the given statement.
         /// Throws an ArgumentNullException if the given statement is null.
+        /// </summary>
         internal static string FormatStatement(QsStatement statement)
         {
             if (statement == null) throw new ArgumentNullException(nameof(statement));
@@ -67,11 +72,13 @@ internal static string FormatStatement(QsStatement statement)
             return ToCode.Output;
         }
 
+        /// <summary>
         /// 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.  
         /// Throws an ArgumentNullException if the given compilation is null.
+        /// </summary>
         private static IEnumerable<string> GenerateQsCode(Compilation compilation, NonNullable<string> file, ILogger logger)
         {
             if (compilation == null) throw new ArgumentNullException(nameof(compilation));
@@ -105,12 +112,14 @@ string FormatComments(IEnumerable<string> comments) =>
             };
         }
 
+        /// <summary>
         /// Generates formatted Q# code for the file with the given uri based on the syntax tree in the given compilation. 
         /// If the id of the file is consistent with the one assigned to a code snippet,
         /// logs the generated code using the given logger. 
         /// Creates a file containing the generated code in the given output folder otherwise.  
         /// Returns true if the generation succeeded, and false if an exception was thrown. 
         /// Throws an ArgumentNullException if the given compilation, the file uri or its absolute path are null.  
+        /// </summary>
         private static bool GenerateFormattedQsFile(Compilation compilation, NonNullable<string> fileName, string outputFolder, ILogger logger)
         {
             if (compilation == null) throw new ArgumentNullException(nameof(compilation));
@@ -137,11 +146,13 @@ private static bool GenerateFormattedQsFile(Compilation compilation, NonNullable
             return true;
         }
 
+        /// <summary>
         /// Builds the compilation for the Q# code or Q# snippet and referenced assemblies defined by the given options.
         /// Generates formatted Q# code for each source file in the compilation. 
         /// Returns a suitable error code if some of the source files or references could not be found or loaded, or if the Q# generation failed.
         /// Compilation errors are not reflected in the return code, but are logged using the given logger. 
         /// Throws an ArgumentNullException if any of the given arguments is null.
+        /// </summary>
         public static int Run(FormatOptions options, ConsoleLogger logger)
         {
             if (options == null) throw new ArgumentNullException(nameof(options));

src/QsCompiler/CommandLineTool/CompilerOptions.cs

@@ -60,7 +60,9 @@ public enum LogFormat
 
         // routines related to logging 
 
+        /// <summary>
         /// If a logger is given, logs the options as CommandLineArguments Information before returning the printed string. 
+        /// </summary>
         public string[] Print(ILogger logger = null)
         {
             string value(PropertyInfo p)
@@ -77,7 +79,9 @@ string value(PropertyInfo p)
             return msg;
         }
 
+        /// <summary>
         /// Given a LogFormat, returns a suitable routing for formatting diagnostics.
+        /// </summary>
         internal static Func<Diagnostic, string> LoggingFormat(LogFormat format)
         {
             switch (format)
@@ -88,8 +92,10 @@ internal static Func<Diagnostic, string> LoggingFormat(LogFormat format)
             }
         }
 
+        /// <summary>
         /// Creates a suitable logger for the given command line options, 
         /// logging the given arguments if the verbosity is high enough.
+        /// </summary>
         public ConsoleLogger GetLogger(DiagnosticSeverity minimumVerbosity = DiagnosticSeverity.Warning)
         {
             var logger = new ConsoleLogger(
@@ -104,7 +110,9 @@ public ConsoleLogger GetLogger(DiagnosticSeverity minimumVerbosity = DiagnosticS
 
         // routines related to processing snippets
 
+        /// <summary>
         /// text document identifier used to identify the code snippet in diagnostic mode
+        /// </summary>
         private static readonly Uri SNIPPET_FILE_URI = new Uri(Path.GetFullPath("__CODE_SNIPPET__.qs"));
         private static NonNullable<string> SNIPPET_FILE_ID
         {
@@ -117,29 +125,39 @@ private static NonNullable<string> SNIPPET_FILE_ID
             }
         }
 
+        /// <summary>
         /// name of the namespace within which code snippets are compiled
+        /// </summary>
         private const string SNIPPET_NAMESPACE = "_CODE_SNIPPET_NS_";
+        /// <summary>
         /// name of the callable within which code snippets are compiled
+        /// </summary>
         private const string SNIPPET_CALLABLE = "_CODE_SNIPPET_CALLABLE_";
 
+        /// <summary>
         /// wraps the given content into a namespace and callable that maps Unit to Unit
+        /// </summary>
         public static string AsSnippet(string content, bool inFunction = false) =>
             $"{Declarations.Namespace} {SNIPPET_NAMESPACE} {{ \n " +
             $"{(inFunction ? Declarations.Function : Declarations.Operation)} {SNIPPET_CALLABLE} () : {Types.Unit} {{ \n" +
             $"{content} \n" + // no indentation such that position info is accurate
             $"}} \n" +
             $"}}";
 
+        /// <summary>
         /// helper function that returns true if the given file id is the one a compilation unit manager would assign to the code snipped 
+        /// </summary>
         public static bool IsCodeSnippet(NonNullable<string> fileId) =>
             fileId.Value == SNIPPET_FILE_ID.Value;
 
 
+        /// <summary>
         /// Returns a function that given a routine for loading files from disk, 
         /// return an enumerable with all text document identifiers and the corresponding file content 
         /// for the source code or Q# snippet specified by the given options. 
         /// If both the Input and the CodeSnippet property are set, or none of these properties is set in the given options, 
         /// logs a suitable error and returns and empty dictionary.
+        /// </summary>
         internal CompilationLoader.SourceLoader LoadSourcesOrSnippet (ILogger logger) => loadFromDisk =>
         {
             bool inputIsEmptyOrNull = this.Input == null || !this.Input.Any();

src/QsCompiler/CommandLineTool/Logging.cs

@@ -23,11 +23,13 @@ public ConsoleLogger(
             DiagnosticSeverity verbosity = DiagnosticSeverity.Warning,
             IEnumerable<int> noWarn = null, int lineNrOffset = 0)
         : base(verbosity, noWarn, lineNrOffset) =>
-            this.ApplyFormatting = format ?? Formatting.HumanReadableFormat; 
+            this.ApplyFormatting = format ?? Formatting.HumanReadableFormat;
 
+        /// <summary>
         /// Prints the given message to the Console. 
         /// Errors and Warnings are printed to the error stream.
         /// Throws an ArgumentNullException if the given message is null. 
+        /// </summary>
         private static void PrintToConsole(DiagnosticSeverity severity, string message)
         {
             if (message == null) throw new ArgumentNullException(nameof(message));
@@ -46,8 +48,10 @@ private static void PrintToConsole(DiagnosticSeverity severity, string message)
             finally { Console.ForegroundColor = consoleColor; }
         }
 
+        /// <summary>
         /// Prints a summary containing the currently counted number of errors, warnings and exceptions.
         /// Indicates a compilation failure if the given status does not correspond to the ReturnCode indicating a success. 
+        /// </summary>
         public virtual void ReportSummary(int status = CommandLineCompiler.ReturnCode.SUCCESS)
         {
             string ItemString(int nr, string name) => $"{nr} {name}{(nr == 1 ? "" : "s")}";

src/QsCompiler/CommandLineTool/TargetOptions.cs

@@ -7,7 +7,9 @@
 
 namespace Microsoft.Quantum.QsCompiler.CommandLineCompiler
 {
+    /// <summary>
     /// command line options for Q# build targets
+    /// </summary>
     public class TargetOptions
     {
         [Option('v', "verbose", Required = false, Default = false,

src/QsCompiler/CompilationManager/AttributeReader.cs

@@ -13,16 +13,20 @@
 
 namespace Microsoft.Quantum.QsCompiler
 {
+    /// <summary>
     /// This class relies on the ECMA-335 standard to extract information contained in compiled binaries. 
     /// The standard can be found here: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-335.pdf,
     /// and the section on custom attributes starts on page 267. 
+    /// </summary>
     public static class AttributeReader
     {
+        /// <summary>
         /// There are two possible handle kinds in use for the constructor of a custom attribute, 
         /// one pointing to the MethodDef table and one to the MemberRef table, see p.216 in the ECMA standard linked above and 
         /// https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/src/System/Reflection/Metadata/TypeSystem/CustomAttribute.cs#L42
         /// This routine extracts the namespace and type name of the given attribute and returns the corresponding string handles. 
         /// Returns null if the constructor handle is not a MethodDefinition or a MemberDefinition. 
+        /// </summary>
         private static (StringHandle, StringHandle)? GetAttributeType(MetadataReader metadataReader, CustomAttribute attribute)
         {
             if (attribute.Constructor.Kind == HandleKind.MethodDefinition)
@@ -64,11 +68,13 @@ private static (string, string)? GetAttribute(MetadataReader metadataReader, Cus
             return null;
         }
 
+        /// <summary>
         /// Given a stream with the bytes of an assembly, read its custom attributes and
         /// returns a tuple containing the name of the attribute and the constructor argument 
         /// for all attributes defined in a Microsoft.Quantum* namespace.  
         /// Throws an ArgumentNullException if the given stream is null. 
         /// Throws the corresponding exceptions if the information cannot be extracted.
+        /// </summary>
         public static IEnumerable<(string, string)> GetQsCompilerAttributes(Stream stream)
         {
             if (stream == null) throw new ArgumentNullException(nameof(stream));
@@ -83,12 +89,14 @@ private static (string, string)? GetAttribute(MetadataReader metadataReader, Cus
             }
         }
 
+        /// <summary>
         /// Given the full name of an assembly, opens the file and reads its custom attributes and
         /// returns a tuple containing the name of the attribute and the constructor argument 
         /// for all attributes defined in the Microsoft.Quantum* namespace.  
         /// Throws an ArgumentNullException if the given uri is null. 
         /// Throws a FileNotFoundException if no file with the given name exists. 
         /// Throws the corresponding exceptions if the information cannot be extracted.
+        /// </summary>
         public static IEnumerable<(string, string)> GetQsCompilerAttributes(Uri asm)
         {
             if (asm == null) throw new ArgumentNullException(nameof(asm));