Adding API Doc to Monitor.

This completes adding API doc to all developer-facing classes: Academy, Agent and Monitor. - Minor refactoring of variable names for spelling correctness: - isInstanciated —> isInstantiated - InstanciateCanvas() —> InstantiateCanvas() - Removed unused imports. - Removing private declarations.
7 年前 · 3679b42d
--- a/unity-environment/Assets/ML-Agents/Scripts/Monitor.cs
+++ b/unity-environment/Assets/ML-Agents/Scripts/Monitor.cs
-using System.Collections;
-using System.Collections.Generic;
-using UnityEngine;
-using UnityEngine.UI;
-using Newtonsoft.Json;
+using System.Collections.Generic;
+using UnityEngine;
-/** The type of monitor the information must be displayed in.
- * <slider> corresponds to a slingle rectangle which width is given
- * by a float between -1 and 1. (green is positive, red is negative)
- * <hist> corresponds to n vertical sliders. 
- * <text> is a text field.
- * <bar> is a rectangle of fixed length to represent the proportions 
- * of a list of floats.
- */ 
+using Newtonsoft.Json;
+
+/// <summary>
+/// The type of monitor the information must be displayed in.
+/// <slider> corresponds to a single rectangle whose width is given
+///     by a float between -1 and 1. (green is positive, red is negative)
+/// <hist> corresponds to n vertical sliders.
+/// <text> is a text field.
+/// <bar> is a rectangle of fixed length to represent the proportions
+///     of a list of floats.
+/// </summary>
 public enum MonitorType
 {
    slider,
 }

-/** Monitor is used to display information. Use the log function to add
- * information to your monitor.
- */ 
+/// <summary>
+/// Monitor is used to display information about the Agent within the Unity
+/// scene. Use the log function to add information to your monitor.
+/// </summary>
+    /// <summary>
+    /// Represents how high above the target the monitors will be.
+    /// </summary>
+    [HideInInspector]
+    static public float verticalOffset = 3f;
-    static bool isInstanciated;
+    static bool isInstantiated;
+    static Dictionary<Transform, Dictionary<string, DisplayValue>> displayTransformValues;
+    static Color[] barColors;
-    private struct DisplayValue
+    struct DisplayValue
-
-    static Dictionary<Transform, Dictionary<string,  DisplayValue>> displayTransformValues;
-    static private Color[] barColors;
-    [HideInInspector]
-    static public float verticalOffset = 3f;
-    /**< \brief This float represents how high above the target the monitors will be. */

    static GUIStyle keyStyle;
    static GUIStyle valueStyle;
    static bool initialized;

-
-    /** Use the Monitor.Log static function to attach information to a transform.
-     * If displayType is <text>, value can be any object. 
-     * If sidplayType is <slider>, value must be a float.
-     * If sidplayType is <hist>, value must be a List or Array of floats.
-     * If sidplayType is <bar>, value must be a list or Array of positive floats.
-     * Note that <slider> and <hist> caps values between -1 and 1.
-     * @param key The name of the information you wish to Log.
-     * @param value The value you want to display.
-     * @param displayType The type of display.
-     * @param target The transform you want to attach the information to.
-     */
+    /// <summary>
+    /// Use the Monitor.Log static function to attach information to a transform.
+    /// If displayType is <text>, value can be any object. 
+    /// If sidplayType is <slider>, value must be a float.
+    /// If sidplayType is <hist>, value must be a List or Array of floats.
+    /// If sidplayType is <bar>, value must be a list or Array of positive floats.
+    /// Note that <slider> and<hist> caps values between -1 and 1.
+    /// </summary>
+    /// <returns>The log.</returns>
+    /// <param name="key">The name of the information you wish to Log.</param>
+    /// <param name="value">The value you want to display.</param>
+    /// <param name="displayType">The type of display.</param>
+    /// <param name="target">
+    /// The transform you want to attach the information to.
+    /// </param>
    public static void Log(
        string key,
        object value,
-        if (!isInstanciated)
+        if (!isInstantiated)
-            InstanciateCanvas();
-            isInstanciated = true;
+            InstantiateCanvas();
+            isInstantiated = true;

        }

        }
    }

-    /** Remove a value from a monitor
-     * @param target The transform to which the information is attached
-     * @param key The key of the information you want to remove
-     */ 
+    /// <summary>
+    /// Remove a value from a monitor.
+    /// </summary>
+    /// <param name="target">
+    /// The transform to which the information is attached.
+    /// </param>
+    /// <param name="key">The key of the information you want to remove.</param>
    public static void RemoveValue(Transform target, string key)
    {
        if (target == null)

    }

-    /** Remove all information from a monitor
-     * @param target The transform to which the information is attached
-     */ 
+    /// <summary>
+    /// Remove all information from a monitor.
+    /// </summary>
+    /// <param name="target">
+    /// The transform to which the information is attached.
+    /// </param>
    public static void RemoveAllValues(Transform target)
    {
        if (target == null)
        {
            displayTransformValues.Remove(target);
        }
-    
+
-    /** Use SetActive to enable or disable the Monitor via script
-     * @param active Set the Monitor's status to the value of active
-     */ 
-    public static void SetActive(bool active){
-        if (!isInstanciated)
+    /// <summary>
+    /// Use SetActive to enable or disable the Monitor via script
+    /// </summary>
+    /// <param name="active">Value to set the Monitor's status to.</param>
+    public static void SetActive(bool active)
+    {
+        if (!isInstantiated)
-            InstanciateCanvas();
-            isInstanciated = true;
+            InstantiateCanvas();
+            isInstantiated = true;

        }
        if (canvas != null)

    }

-    private static void InstanciateCanvas()
+    /// Initializes the canvas.
+    static void InstantiateCanvas()
    {
        canvas = GameObject.Find("AgentMonitorCanvas");
        if (canvas == null)
            canvas.AddComponent<Monitor>();
        }
-        displayTransformValues = new Dictionary<Transform, Dictionary< string , DisplayValue>>();
+        displayTransformValues = new Dictionary<Transform, Dictionary<string, DisplayValue>>();
+    /// Convert the input object to a float array. Returns a float[0] if the
+    /// conversion process fails.
    float[] ToFloatArray(object input)
    {
        try
        }
        catch
        {
-            
+
        }
        try
        {
        }
        catch
        {
-            
+
+    /// <summary> <inheritdoc/> </summary>
    void OnGUI()
    {
        if (!initialized)
                displayTransformValues.Remove(target);
                continue;
            }
- 
+
            float widthScaler = (Screen.width / 1000f);
            float keyPixelWidth = 100 * widthScaler;
            float keyPixelHeight = 20 * widthScaler;
            {
                continue;
            }
-                
+

            Dictionary<string, DisplayValue> displayValues = displayTransformValues[target];

                    valueStyle.alignment = TextAnchor.MiddleLeft;
                    GUI.Label(new Rect(
                            origin.x + paddingwidth + keyPixelWidth,
-                            origin.y - (index + 1) * keyPixelHeight, 
-                            keyPixelWidth, keyPixelHeight), 
+                            origin.y - (index + 1) * keyPixelHeight,
+                            keyPixelWidth, keyPixelHeight),
                        JsonConvert.SerializeObject(displayValues[key].value, Formatting.None), valueStyle);

                }
-                    if (displayValues[key].value.GetType() == typeof(float))
+                    if (displayValues[key].value is float)
                    {
                        sliderValue = (float)displayValues[key].value;
                    }
                    }
                    GUI.Box(new Rect(
                            origin.x + paddingwidth + keyPixelWidth,
-                            origin.y - (index + 0.9f) * keyPixelHeight, 
-                            keyPixelWidth * sliderValue, keyPixelHeight * 0.8f), 
+                            origin.y - (index + 0.9f) * keyPixelHeight,
+                            keyPixelWidth * sliderValue, keyPixelHeight * 0.8f),
                        GUIContent.none, s);

                }
                        }
                        GUI.Box(new Rect(
                                origin.x + paddingwidth + keyPixelWidth + (keyPixelWidth * histWidth + paddingwidth / 2) * i,
-                                origin.y - (index + 0.1f) * keyPixelHeight, 
-                                keyPixelWidth * histWidth, -keyPixelHeight * value), 
+                                origin.y - (index + 0.1f) * keyPixelHeight,
+                                keyPixelWidth * histWidth, -keyPixelHeight * value),
                            GUIContent.none, s);
                    }

                {
                    float[] vals = ToFloatArray(displayValues[key].value);
                    float valsSum = 0f;
-                    float valsCum = 0f; 
+                    float valsCum = 0f;
                    foreach (float f in vals)
                    {
                        valsSum += Mathf.Max(f, 0);
                            float value = Mathf.Max(vals[i], 0) / valsSum;
                            GUI.Box(new Rect(
                                    origin.x + paddingwidth + keyPixelWidth + keyPixelWidth * valsCum,
-                                    origin.y - (index + 0.9f) * keyPixelHeight, 
-                                    keyPixelWidth * value, keyPixelHeight * 0.8f), 
+                                    origin.y - (index + 0.9f) * keyPixelHeight,
+                                    keyPixelWidth * value, keyPixelHeight * 0.8f),
                                GUIContent.none, colorStyle[i % colorStyle.Length]);
                            valsCum += value;

        }
    }

+    /// Helper method used to initialize the GUI. Called once.
    void Initialize()
    {
        keyStyle = GUI.skin.label;
-        barColors = new Color[6]{ Color.magenta, Color.blue, Color.cyan, Color.green, Color.yellow, Color.red };
+        barColors = new Color[6] { Color.magenta, Color.blue, Color.cyan, Color.green, Color.yellow, Color.red };
        colorStyle = new GUIStyle[barColors.Length];
        for (int i = 0; i < barColors.Length; i++)
        {