Documentation suggestions

@andybak I would like to use my knowledge of things like ModelWidget, LightWidget, BreakModelApartCommand, etc to write some docs in Developer Notes and add more comments to the codebase.

(1) what do you think about this XML Documentation Comment? This

SetLightType

SetLightType

method is in

LightWidget

LightWidget

. I think some methods like this one could have these comments added, as when you hover over them you see the description. But something like

LightWidget.Clone

LightWidget.Clone

may not need comments (except maybe some remarks) as

Clone

Clone

is pretty standard and you can read the code to see what it does. I think this

SetLightType

SetLightType

method is a good example because I personally genuinely thought it was used to modify the lightwidget's Light type.

   /// <summary>
        /// Activates all lights of the specified type and deactivates all other lights that are children of this LightWidget's GameObject.
        /// </summary>
        /// <param name="lightType">The type of light to activate</param>
        /// <returns>
        /// The last <see cref="Light"/> object in the hierarchy that is activated, or <c>null</c> if no matching light type is found.
        /// </returns>
        private Light SetLightType(LightType lightType)
        {
            var lights = gameObject.GetComponentsInChildren<Light>();
            Light activeLight = null;
            foreach (var l in lights)
            {
                l.gameObject.SetActive(false);
                if (l.type == lightType)
                {
                    l.gameObject.SetActive(true);
                    activeLight = l;
                }

            }
            return activeLight;
        }

   /// <summary>
        /// Activates all lights of the specified type and deactivates all other lights that are children of this LightWidget's GameObject.
        /// </summary>
        /// <param name="lightType">The type of light to activate</param>
        /// <returns>
        /// The last <see cref="Light"/> object in the hierarchy that is activated, or <c>null</c> if no matching light type is found.
        /// </returns>
        private Light SetLightType(LightType lightType)
        {
            var lights = gameObject.GetComponentsInChildren<Light>();
            Light activeLight = null;
            foreach (var l in lights)
            {
                l.gameObject.SetActive(false);
                if (l.type == lightType)
                {
                    l.gameObject.SetActive(true);
                    activeLight = l;
                }

            }
            return activeLight;
        }

Documentation suggestions

SetLightType

SetLightType

method is in

LightWidget

LightWidget

. I think some methods like this one could have these comments added, as when you hover over them you see the description. But something like

LightWidget.Clone

LightWidget.Clone

may not need comments (except maybe some remarks) as

Clone

Clone

is pretty standard and you can read the code to see what it does. I think this

SetLightType

SetLightType

method is a good example because I personally genuinely thought it was used to modify the lightwidget's Light type.

   /// <summary>
        /// Activates all lights of the specified type and deactivates all other lights that are children of this LightWidget's GameObject.
        /// </summary>
        /// <param name="lightType">The type of light to activate</param>
        /// <returns>
        /// The last <see cref="Light"/> object in the hierarchy that is activated, or <c>null</c> if no matching light type is found.
        /// </returns>
        private Light SetLightType(LightType lightType)
        {
            var lights = gameObject.GetComponentsInChildren<Light>();
            Light activeLight = null;
            foreach (var l in lights)
            {
                l.gameObject.SetActive(false);
                if (l.type == lightType)
                {
                    l.gameObject.SetActive(true);
                    activeLight = l;
                }

            }
            return activeLight;
        }

   /// <summary>
        /// Activates all lights of the specified type and deactivates all other lights that are children of this LightWidget's GameObject.
        /// </summary>
        /// <param name="lightType">The type of light to activate</param>
        /// <returns>
        /// The last <see cref="Light"/> object in the hierarchy that is activated, or <c>null</c> if no matching light type is found.
        /// </returns>
        private Light SetLightType(LightType lightType)
        {
            var lights = gameObject.GetComponentsInChildren<Light>();
            Light activeLight = null;
            foreach (var l in lights)
            {
                l.gameObject.SetActive(false);
                if (l.type == lightType)
                {
                    l.gameObject.SetActive(true);
                    activeLight = l;
                }

            }
            return activeLight;
        }

Documentation suggestions

Similar Threads

Documentation suggestions

Similar Threads

Similar Threads

Similar Threads