Merge pull request googlesamples#383 from Si1ver/better-xml-docs

Improved inline xml documentation

Author: chkuang-g

source/AndroidResolver/src/AndroidAbis.cs

@@ -143,7 +143,7 @@ public AndroidAbis(IEnumerable<string> abisSet) {
     /// <summary>
     /// Create a set of ABIs from a comma separated set of ABI strings.
     /// </summary>
-    /// <param name="abisSet">Set of ABI strings.</param>
+    /// <param name="abiString">Comma separated set of ABI strings.</param>
     public AndroidAbis(string abiString) {
         if (String.IsNullOrEmpty(abiString)) {
             abis = new HashSet<string>(Supported);
@@ -190,7 +190,7 @@ public override bool Equals(System.Object obj) {
     /// Get the supported set of Android ABIs for the current Unity version.
     /// The dictionary maps the official Android ABI name (i.e the directory name looked up by the
     /// operating system) to the UnityEditor.AndroidTargetDevice (Unity 5.x & 2017.x) or
-    // UnityEditor.AndroidArchitecture enumeration value name.
+    /// UnityEditor.AndroidArchitecture enumeration value name.
     /// </summary>
     private static Dictionary<string, string> SupportedAbiToAbiEnumValue {
         get { return PropertyConfiguration.Instance.SupportedAbiToAbiEnumValue; }
@@ -221,10 +221,10 @@ public static IEnumerable<string> AllSupported {
     /// </summary>
     /// <param name="enumValueObject">Enum object to convert.</param>
     private static ulong EnumValueObjectToULong(object enumValueObject) {
-        /// Flags enum values can't be cast directly to an integral type, however it is possible to
-        /// print the value as an integer string so convert to a string and then parse as an int.
-        /// Enums are considered unsigned by the formatter, so if an enum is defined as -1 it will
-        /// be formatted as UInt32.MaxValue, i.e. 4294967295.
+        // Flags enum values can't be cast directly to an integral type, however it is possible to
+        // print the value as an integer string so convert to a string and then parse as an int.
+        // Enums are considered unsigned by the formatter, so if an enum is defined as -1 it will
+        // be formatted as UInt32.MaxValue, i.e. 4294967295.
         return UInt64.Parse(String.Format("{0:D}", enumValueObject));
     }
 
@@ -240,7 +240,7 @@ private static ulong EnumValueStringToULong(Type enumType, string enumValueStrin
     /// <summary>
     /// Get / set the target device ABI (Unity >= 5.0.x)
     /// Unity >= 2017.4 supports armeabi-v7a, arm64-v8a, x86 & fat (i.e armeabi-v7a, arm64, x86)
-    /// Unity >= 5.0.x & <= 2017.3 only support armeabi-v7a, x86 & fat (i.e armeabi-v7a & x86)
+    /// Unity >= 5.0.x & &lt;= 2017.3 only support armeabi-v7a, x86 & fat (i.e armeabi-v7a & x86)
     /// </summary>
     public static AndroidAbis Current {
         set {

source/AndroidResolver/src/AndroidSdkManager.cs

@@ -975,7 +975,7 @@ internal class AndroidSdkManager {
         /// </summary>
         /// <param name="toolName">Name of the tool to search for.</param>
         /// <param name="sdkPath">SDK path to search for the tool.  If this is null or empty, the
-        // system path is searched instead.</param>
+        /// system path is searched instead.</param>
         /// <returns>String with the path to the tool if found, null otherwise.</returns>
         private static string FindAndroidSdkTool(string toolName, string sdkPath = null) {
             if (String.IsNullOrEmpty(sdkPath)) {

source/AndroidResolver/src/CommandLine.cs

@@ -375,7 +375,7 @@ public LineReader(IOHandler handler = null)
             /// a newline isn't present.
             /// </summary>
             /// <param name="handle">Handle of the stream to query.</param>
-            /// <returns>List of data for the requested stream.</return>
+            /// <returns>List of data for the requested stream.</returns>
             public List<StreamData> GetBufferedData(int handle)
             {
                 List<StreamData> handleData;
@@ -397,7 +397,6 @@ public void Flush()
             /// <summary>
             /// Aggregate the specified list of StringBytes into a single structure.
             /// </summary>
-            /// <param name="handle">Stream handle.</param>
             /// <param name="dataStream">Data to aggregate.</param>
             public static StreamData Aggregate(List<StreamData> dataStream)
             {

source/AndroidResolver/src/EmbeddedResource.cs

@@ -132,7 +132,7 @@ public bool Extract(Logger logger) {
         /// directories if they're required.
         /// </summary>
         /// <param name="assembly">Assembly to extract resources from.</param>
-        /// <param name="resourceNameToTargetPath">Each Key is the resource to extract and each
+        /// <param name="resourceNameToTargetPaths">Each Key is the resource to extract and each
         /// Value is the path to extract to. If the resource name (Key) is null or empty, this
         /// method will attempt to extract a resource matching the filename component of the path.
         /// </param>

source/AndroidResolver/src/GradleResolver.cs

@@ -139,7 +139,7 @@ internal static Dictionary<string, string> DependenciesToPackageSpecs(
         /// * Path relative to project folder, ex."Assets/Firebase/m2repository"
         /// </summary>
         /// <param name="repoPath">Repo path to convert.</param>
-        /// <param name="sourceLocation>XML or source file this path is referenced from. If this is
+        /// <param name="sourceLocation">XML or source file this path is referenced from. If this is
         /// null the calling method's source location is used when logging the source of this
         /// repo declaration.</param>
         /// <returns>URI to the repo.</returns>
@@ -1025,16 +1025,20 @@ private string DetermineExplodedAarPath(string aarPath) {
         /// <summary>
         /// Processes the aars.
         /// </summary>
-        /// <remarks>Each aar copied is inspected and determined if it should be
+        /// <remarks>
+        /// <para>
+        /// Each aar copied is inspected and determined if it should be
         /// exploded into a directory or not. Unneeded exploded directories are
         /// removed.
+        /// </para>
         /// <para>
         /// Exploding is needed if the version of Unity is old, or if the artifact
         /// has been explicitly flagged for exploding.  This allows the subsequent
         /// processing of variables in the AndroidManifest.xml file which is not
         /// supported by the current versions of the manifest merging process that
         /// Unity uses.
         /// </para>
+        /// </remarks>
         /// <param name="dir">The directory to process.</param>
         /// <param name="updatedFiles">Set of files that were recently updated and should be
         /// processed.</param>

source/AndroidResolver/src/GradleWrapper.cs

@@ -133,7 +133,7 @@ public bool Extract(Logger logger) {
         /// <param name="buildScript">Path to the Gradle build script to use.</param>
         /// <param name="projectProperties">Project properties to use when running the script.
         /// </param>
-        /// <param name="arguments>Other arguments to pass to Gradle.</param>
+        /// <param name="arguments">Other arguments to pass to Gradle.</param>
         /// <param name="logger">Logger to report errors to.</param>
         /// <param name="executeCommand">Closure which takes the tool path to execute
         /// (gradle wrapper) and a string of arguments returning true if successful,

source/AndroidResolver/src/JavaUtilities.cs

@@ -132,7 +132,7 @@ private static string JavaHomeBinaryPath(string javaTool) {
         /// <summary>
         /// Find a Java tool.
         /// </summary>
-        /// <param name="toolName">Name of the tool to search for.</param>
+        /// <param name="javaTool">Name of the tool to search for.</param>
         /// <returns>Path to the tool if it's found, throws a ToolNotFoundException
         /// otherwise.</returns>
         private static string FindJavaTool(string javaTool)

source/AndroidResolver/src/LocalMavenRepository.cs

@@ -82,7 +82,7 @@ public static List<string> FindAarsInLocalRepos(ICollection<Dependency> dependen
         /// <summary>
         /// Get a path without a filename extension.
         /// </summary>
-        /// <param name="filename">Path to a file.</param>
+        /// <param name="path">Path to a file.</param>
         /// <returns>Path (including directory) without a filename extension.</returns>
         internal static string PathWithoutExtension(string path) {
             return Path.Combine(Path.GetDirectoryName(path),

source/AndroidResolver/src/PlayServicesResolver.cs

@@ -261,7 +261,7 @@ private static string SetToString(HashSet<string> setToConvert) {
             /// <summary>
             /// Convert a dictionary to a sorted comma separated string.
             /// </summary>
-            /// <returns>Comma separated string in the form key=value.<returns>
+            /// <returns>Comma separated string in the form key=value.</returns>
             private static string DictionaryToString(Dictionary<string, string> dict) {
                 var components = new List<string>();
                 foreach (var key in SortSet(dict.Keys)) {
@@ -319,7 +319,7 @@ internal class PropertyPoller<T> {
             /// <param name="delayTimeInSeconds">Time to wait before signalling that the value
             /// has changed.</param>
             /// <param name="checkIntervalInSeconds">Time to check the value of the property for
-            /// changes.<param>
+            /// changes.</param>
             public PropertyPoller(string propertyName,
                                   int delayTimeInSeconds = 3,
                                   int checkIntervalInSeconds = 1) {
@@ -628,7 +628,7 @@ public static bool GradleProjectExportEnabled {
         /// </summary>
         private struct AndroidBuildSystemSettings {
             /// <summary>
-            // Whether the Gradle build is enabled.
+            /// Whether the Gradle build is enabled.
             /// </summary>
             public bool GradleBuildEnabled { get; private set; }
 
@@ -638,7 +638,7 @@ private struct AndroidBuildSystemSettings {
             public bool GradleTemplateEnabled { get; private set; }
 
             /// <summary>
-            // Whether project export is enabled.
+            /// Whether project export is enabled.
             /// </summary>
             public bool ProjectExportEnabled { get; private set; }
 
@@ -656,7 +656,7 @@ public static AndroidBuildSystemSettings Current {
             }
 
             /// <summary>
-            // Compare with another AndroidBuildSystemSettings.
+            /// Compare with another AndroidBuildSystemSettings.
             /// </summary>
             /// <param name="obj">Object to compare with.</param>
             /// <returns>true if the object is the same as this, false otherwise.</returns>
@@ -1217,7 +1217,7 @@ private static void Reresolve() {
         /// * foo.com.my.app.service --> foo.com.my.app.service (unchanged)
         /// </param>
         /// <param name="path">Path of this node in the hierarchy of nodes. For example:
-        /// given node is "<c>" in "<a><b><c>" this should be "a/b/c".  If this
+        /// given node is "&lt;c>" in "&lt;a>&lt;b>&lt;c>" this should be "a/b/c".  If this
         /// value is null the name of the current node is used.</param>
         /// <returns>true if any replacements are applied, false otherwise.</returns>
         private static bool ReplaceVariablesInXmlElementTree(

source/AndroidResolver/src/UnityCompat.cs

@@ -399,7 +399,7 @@ public static int FindNewestInstalledAndroidSDKVersion() {
     /// </summary>
     /// Unfortunately the Unity API does not provide a way to get the current BuildTargetGroup from
     /// the currently active BuildTarget.
-    /// <param name="target">BuildTarget to convert.</param>
+    /// <param name="buildTarget">BuildTarget to convert.</param>
     /// <returns>BuildTargetGroup enum value.</returns>
     private static BuildTargetGroup ConvertBuildTargetToBuildTargetGroup(BuildTarget buildTarget) {
         var buildTargetToGroup = new Dictionary<string, string>() {

source/AndroidResolver/test/src/AndroidResolverIntegrationTests.cs

@@ -684,6 +684,7 @@ private static void ResolveWithGradleTemplate(
     /// This filters all Unity .meta files from the resultant list.
     /// </summary>
     /// <param name="searchDir">Directory to search.</param>
+    /// <param name="filesToIgnore">Set of files to relative to the generatedAssetsDir.</param>
     /// <param name="relativeDir">Root path for relative filenames.  This should be any directory
     /// under the specified searchDir argument.  If this is null, searchDir is used.</param>
     /// <returns>Dictionary of file paths mapped to relative file paths.</returns>

source/IOSResolver/src/IOSResolver.cs

@@ -72,7 +72,7 @@ private class Pod {
         /// Since order is important sources specified in this list
         /// are interleaved across each Pod added to the resolver.
         /// e.g Pod1.source[0], Pod2.source[0] ...
-        ////    Pod1.source[1], Pod2.source[1] etc.
+        ///     Pod1.source[1], Pod2.source[1] etc.
         ///
         /// See: https://guides.cocoapods.org/syntax/podfile.html#source
         /// </summary>
@@ -186,9 +186,9 @@ public Pod(string name, string version, bool bitcodeEnabled, string minTargetSdk
 
         /// <summary>
         /// Convert min target SDK to an integer in the form
-        // (major * 10) + minor.
+        /// (major * 10) + minor.
         /// </summary>
-        /// <return>Numeric minimum SDK revision required by this pod.</return>
+        /// <returns>Numeric minimum SDK revision required by this pod.</returns>
         public int MinTargetSdkToVersion() {
             string sdkString =
                 String.IsNullOrEmpty(minTargetSdk) ? "0.0" : minTargetSdk;
@@ -1349,7 +1349,7 @@ static int TargetSdkVersion {
 
     /// <summary>
     /// Convert a target SDK string into a value of the form
-    // (major * 10) + minor.
+    /// (major * 10) + minor.
     /// </summary>
     /// <returns>Integer representation of the SDK.</returns>
     internal static int TargetSdkStringToVersion(string targetSdk) {
@@ -1385,7 +1385,7 @@ internal static string TargetSdkVersionToString(int version) {
     /// <summary>
     /// Determine whether any pods need bitcode disabled.
     /// </summary>
-    /// <returns>List of pod names with bitcode disabled.</return>
+    /// <returns>List of pod names with bitcode disabled.</returns>
     private static List<string> FindPodsWithBitcodeDisabled() {
         var disabled = new List<string>();
         foreach (var pod in pods.Values) {
@@ -1858,7 +1858,7 @@ private static void ParseUnityDeps(string unityPodfilePath) {
     /// this returns the string...
     ///
     /// source 'http://myrepo.com/Specs.git'
-    /// source 'http://anotherrepo.com/Specs.git'
+    /// source 'http://anotherrepo.com/Specs.git'</returns>
     private static string GeneratePodfileSourcesSection() {
         var interleavedSourcesLines = new List<string>();
         var processedSources = new HashSet<string>();
@@ -2083,7 +2083,7 @@ private class DelegateContainer<T> {
         /// Delegate method associated with the container.  This enables the
         /// following pattern:
         ///
-        /// var container = new DelegateContainer<CommandLine.CompletionHandler>();
+        /// var container = new DelegateContainer&lt;CommandLine.CompletionHandler>();
         /// container.Handler = (CommandLine.Result result) => { RunNext(container.Handler); };
         /// </summary>
         public T Handler { get; set; }

source/IntegrationTester/src/Runner.cs

@@ -116,7 +116,6 @@ public static void ScheduleTestCases(IEnumerable<TestCase> tests) {
         /// <summary>
         /// Add a single test case to the list to be executed.
         /// </summary>
-        /// <remarks>
         /// <param name="test">Test case to add to the list to execute.</param>
         public static void ScheduleTestCase(TestCase test) {
             testCases.Add(test);
@@ -139,7 +138,6 @@ public static void VersionHandlerReady() {
         /// <remarks>
         /// Finds and calls all initialization methods with the InitializerAttribute.
         /// </remarks>
-        /// <param name="unityVersion">Major & minor version of Unity.</param>
         private static void ConfigureTestCases() {
             unityVersion = Google.VersionHandler.GetUnityVersionMajorMinor();
 
@@ -332,8 +330,8 @@ private static List<TestCaseResult> ReadTestCaseResults() {
         }
 
         /// <summary>
-        // Log a test case result to the journal so that it isn't executed again if the app
-        // domain is reloaded.
+        /// Log a test case result to the journal so that it isn't executed again if the app
+        /// domain is reloaded.
         /// </summary>
         private static bool WriteTestCaseResult(TestCaseResult testCaseResult) {
             var existingTestCaseResults = ReadTestCaseResults();

source/PackageManagerResolver/src/PackageManagerClient.cs

@@ -56,7 +56,9 @@ public Wrapper(object instance) {
         /// Convert a collection of objects to a field separated string.
         /// </summary>
         /// <param name="objects">Collection of objects to convert to a list of strings.</param>
-        /// <returns>Comma separated string.</returns>.
+        /// <param name="separator">The string to use as a separator.</param>
+        /// <returns>A string that consists of members of <paramref name="objects"/> delimited
+        /// by <paramref name="separator"/> string.</returns>.
         protected static string ObjectCollectionToString<T>(IEnumerable<T> objects,
                                                             string separator) {
             var components = new List<string>();
@@ -968,7 +970,7 @@ private class EnumeratorProgressReporter {
         /// Construct the instance.
         /// </summary>
         /// <param name="items">Items to iterate through.</param>
-        /// <param name="progress">Reports progress as iteration proceeds.</param>
+        /// <param name="progressReporter">Reports progress as iteration proceeds.</param>
         public EnumeratorProgressReporter(ICollection<string> items,
                                    Action<float, string> progressReporter) {
             itemCount = items.Count;
@@ -1081,6 +1083,7 @@ private class PackageInstaller : EnumeratorProgressReporter {
         /// Install a set of packages using the package manager.
         /// </summary>
         /// <param name="packageIdsOrNames">Package IDs or names to search for.</param>
+        /// <param name="complete">Called when the operation is complete.</param>
         /// <param name="progress">Reports progress through the search.</param>
         public PackageInstaller(ICollection<string> packageIdsOrNames,
                                 Action<Dictionary<string, InstallResult>> complete,
@@ -1163,6 +1166,7 @@ private class PackageSearcher : EnumeratorProgressReporter {
         /// Search for a set of packages in the package manager.
         /// </summary>
         /// <param name="packageIdsOrNames">Package IDs or names to search for.</param>
+        /// <param name="complete">Called when the operation is complete.</param>
         /// <param name="progress">Reports progress through the search.</param>
         public PackageSearcher(ICollection<string> packageIdsOrNames,
                                Action<Dictionary<string, SearchResult>> complete,
@@ -1245,6 +1249,7 @@ public static void AddPackage(string packageIdOrName, Action<InstallResult> comp
     /// Add packages to the project.
     /// </summary>
     /// <param name="packageIdsOrNames">IDs or names of the packages to add.</param>
+    /// <param name="complete">Called when the operation is complete.</param>
     /// <param name="progress">Reports progress through the installation.</param>
     public static void AddPackages(ICollection<string> packageIdsOrNames,
                                    Action<Dictionary<string, InstallResult>> complete,

source/PackageManagerResolver/src/PackageManagerRegistry.cs

@@ -80,7 +80,7 @@ public PackageManagerRegistry() {
         /// <summary>
         /// Convert to a human readable string excluding the TermsOfService and CreatedBy fields.
         /// </summary>
-        /// <returns>String representation of this instance.</return>
+        /// <returns>String representation of this instance.</returns>
         public override string ToString() {
             return String.Format("name: {0}, url: {1}, scopes: {2}",
                                  Name, Url,