Merge pull request #901 from uni-bremen-agst/fix/documentation-style

Refactor XML documentation – part 1

Author: koschke

Assets/SEE/Audio/AudioGameObject.cs

@@ -65,7 +65,7 @@ public bool Mute
         /// Default Constructor
         /// </summary>
         /// <param name="attachedObject">The game object this audio management object is attached to.</param>
-        /// <param name="volume">The audio volume</param>
+        /// <param name="volume">The audio volume.</param>
         /// <param name="muted">Whether or not the audio should be muted.</param>
         public AudioGameObject(GameObject attachedObject, float volume = 1.0f, bool muted = false)
         {

Assets/SEE/CameraPaths/CameraPath.cs

@@ -73,8 +73,8 @@ private CameraPath(string path)
         ///
         /// Precondition: 0 <= key < Count.
         /// </summary>
-        /// <param name="key">the index of the path entry to be returned</param>
-        /// <returns>key'th entry in the path</returns>
+        /// <param name="key">The index of the path entry to be returned.</param>
+        /// <returns>Key'th entry in the path.</returns>
         public PathData this[int key]
         {
             get => data[key];
@@ -85,9 +85,9 @@ public PathData this[int key]
         /// Adds the data captured about a particular camera position and rotation in a path
         /// at a given point in time.
         /// </summary>
-        /// <param name="position">position of the camera</param>
-        /// <param name="rotation">rotation of the camera</param>
-        /// <param name="time">point in time in seconds since game start</param>
+        /// <param name="position">Position of the camera.</param>
+        /// <param name="rotation">Rotation of the camera.</param>
+        /// <param name="time">Point in time in seconds since game start.</param>
         public void Add(Vector3 position, Quaternion rotation, float time)
         {
             data.Add(new PathData(position, rotation, time));
@@ -102,7 +102,7 @@ public void Add(Vector3 position, Quaternion rotation, float time)
         /// vector, the second three entries the rotation in Euler angles, and the
         /// the last entry contains the time. Each value is a float.
         /// </summary>
-        /// <param name="filename">name of the output file</param>
+        /// <param name="filename">Name of the output file.</param>
         public void Save(string filename)
         {
             List<string> outputs = new();
@@ -129,8 +129,8 @@ public void Save(string filename)
         /// Converts a float value to a string with two digits and a period as a
         /// decimal separator.
         /// </summary>
-        /// <param name="value">the value to be converted</param>
-        /// <returns>the float as a string in the requested format</returns>
+        /// <param name="value">The value to be converted.</param>
+        /// <returns>The float as a string in the requested format.</returns>
         private static string FloatToString(float value)
         {
             return value.ToString("0.0", System.Globalization.CultureInfo.InvariantCulture);
@@ -164,7 +164,7 @@ private static string FloatToString(float value)
         ///
         /// May throw any exception that can be thrown by System.IO.File.ReadAllLines.
         /// </summary>
-        /// <param name="filename">name of the file containing the path data</param>
+        /// <param name="filename">Name of the file containing the path data.</param>
         public static CameraPath ReadPath(string filename)
         {
             string[] data = System.IO.File.ReadAllLines(filename);
@@ -212,7 +212,7 @@ public static CameraPath ReadPath(string filename)
         ///
         /// Implements interface IEnumerable.
         /// </summary>
-        /// <returns>an enumerator over all path data entries in the path</returns>
+        /// <returns>An enumerator over all path data entries in the path.</returns>
         public IEnumerator GetEnumerator()
         {
             return data.GetEnumerator();
@@ -225,7 +225,7 @@ public IEnumerator GetEnumerator()
         /// this direction. The whole path data is created as a single static root game object tagged
         /// by Tags.Path whose children represent the movements and the lookouts.
         /// </summary>
-        /// <returns>game object representing the path</returns>
+        /// <returns>Game object representing the path.</returns>
         public GameObject Draw()
         {
             GameObject result = new(string.IsNullOrEmpty(path) ? "anonymous path" : path)
@@ -247,8 +247,8 @@ public GameObject Draw()
         /// the direction the camera has looked in this path group. The length of this line
         /// is proportional to the sum over all times of the elements of a path group.
         /// </summary>
-        /// <param name="pathGameObject">the parent the game objects created here are to become
-        /// children of</param>
+        /// <param name="pathGameObject">The parent the game objects created here are to become
+        /// children of.</param>
         private void DrawLookOuts(GameObject pathGameObject)
         {
             int i = 0;
@@ -295,10 +295,10 @@ private void DrawLookOuts(GameObject pathGameObject)
         /// of their co-ordinates are not greater than the given allowed difference.
         /// Returns 1 or -1, respectively, if the vectors are not similar enough.
         /// </summary>
-        /// <param name="me">one vector to be compared</param>
-        /// <param name="other">other vector to be compared against the first one</param>
-        /// <param name="allowedDifference">allowable difference between co-ordinates</param>
-        /// <returns>0 if similar, -1 or 1 if dissimilar</returns>
+        /// <param name="me">One vector to be compared.</param>
+        /// <param name="other">Other vector to be compared against the first one.</param>
+        /// <param name="allowedDifference">Allowable difference between co-ordinates.</param>
+        /// <returns>0 if similar, -1 or 1 if dissimilar.</returns>
         private static int CompareTo(Vector3 me, Vector3 other, float allowedDifference)
         {
             {
@@ -334,8 +334,8 @@ private static int CompareTo(Vector3 me, Vector3 other, float allowedDifference)
         /// The order of the resulting aggregated path is arbitrary. It will not be consistent
         /// with the order of the given path.
         /// </summary>
-        /// <param name="path"></param>
-        /// <returns>path aggregation</returns>
+        /// <param name="path">.</param>
+        /// <returns>Path aggregation.</returns>
         private static List<PathData> Aggregate(List<PathData> path)
         {
             if (path.Count <= 1)
@@ -385,10 +385,10 @@ private static List<PathData> Aggregate(List<PathData> path)
         /// Compares the first argument against the second one based on the similarity
         /// of their position and rotation (ignoring time).
         /// </summary>
-        /// <param name="x">first argument</param>
-        /// <param name="y">second argument to be compared to the first argument</param>
+        /// <param name="x">First argument.</param>
+        /// <param name="y">Second argument to be compared to the first argument.</param>
         /// <returns>0 if x and y are similar, 1 if x is before y, otherwise -1 (the 'before'
-        /// relation is arbitrary)</returns>
+        /// relation is arbitrary).</returns>
         private static int CompareTo(PathData x, PathData y)
         {
             // The following value defines the difference below we still consider two
@@ -410,7 +410,7 @@ private static int CompareTo(PathData x, PathData y)
         /// is created as a line rendering becoming a component of the given object
         /// representing the path.
         /// </summary>
-        /// <param name="pathGameObject"></param>
+        /// <param name="pathGameObject">.</param>
         private void DrawPath(GameObject pathGameObject)
         {
             LineRenderer line = pathGameObject.AddComponent<LineRenderer>();
@@ -444,8 +444,8 @@ private void DrawPath(GameObject pathGameObject)
         /// <summary>
         /// Returns <paramref name="v"/> as a string for debugging.
         /// </summary>
-        /// <param name="v">vector to be turned into a string</param>
-        /// <returns><paramref name="v"/> as a string</returns>
+        /// <param name="v">Vector to be turned into a string.</param>
+        /// <returns><paramref name="v"/> as a string.</returns>
         private static string Dump(Vector3 v)
         {
             return ("(" + v.x.ToString("0.00000")

Assets/SEE/CameraPaths/CameraRecorder.cs

@@ -69,8 +69,8 @@ public class CameraRecorder : MonoBehaviour
         /// Returns the filename that does not currently exist taking into
         /// account the path, basename, take, and extension.
         /// </summary>
-        /// <param name="objectName">the name of the tracked object to be added to the filename</param>
-        /// <returns>filename for the recording</returns>
+        /// <param name="objectName">The name of the tracked object to be added to the filename.</param>
+        /// <returns>Filename for the recording.</returns>
         private string Filename(string objectName)
         {
             string result = NewName(Directory, Basename, objectName, Take, CameraPath.DotPathFileExtension);
@@ -87,12 +87,12 @@ private string Filename(string objectName)
         /// account the path, basename, take, and extension. This filename may or
         /// may not already exist.
         /// </summary>
-        /// <param name="path">leading path</param>
-        /// <param name="basename">base name of the file</param>
-        /// <param name="objectName">the name of the tracked object to be added to the filename</param>
-        /// <param name="take">the number of the take</param>
-        /// <param name="extension">file extension</param>
-        /// <returns>filename for the recording as a concatenation of all given input parameters</returns>
+        /// <param name="path">Leading path.</param>
+        /// <param name="basename">Base name of the file.</param>
+        /// <param name="objectName">The name of the tracked object to be added to the filename.</param>
+        /// <param name="take">The number of the take.</param>
+        /// <param name="extension">File extension.</param>
+        /// <returns>Filename for the recording as a concatenation of all given input parameters.</returns>
         private static string NewName(string path, string basename, string objectName, int take, string extension)
         {
             if (!path.EndsWith(Path.DirectorySeparatorChar.ToString()))
@@ -127,8 +127,8 @@ private void Start()
         /// <summary>
         /// Retrieves all objects to be tracked from the scene including the main camera.
         /// </summary>
-        /// <param name="trackedObjects">the name of the objects to be tracked</param>
-        /// <returns>all objects to be tracked</returns>
+        /// <param name="trackedObjects">The name of the objects to be tracked.</param>
+        /// <returns>All objects to be tracked.</returns>
         private static GameObject[] GetTrackedObjects(string[] trackedObjects)
         {
             if (trackedObjects == null || trackedObjects.Length == 0)

Assets/SEE/CameraPaths/PathData.cs

@@ -15,9 +15,9 @@ public struct PathData
         /// <summary>
         /// Sets the data captured about a particular position in a path at a given point in time.
         /// </summary>
-        /// <param name="position">position of the camera</param>
-        /// <param name="rotation">rotation of the camera</param>
-        /// <param name="time">point in time in seconds since game start</param>
+        /// <param name="position">Position of the camera.</param>
+        /// <param name="rotation">Rotation of the camera.</param>
+        /// <param name="time">Point in time in seconds since game start.</param>
         public PathData(Vector3 position, Quaternion rotation, float time)
         {
             this.Position = position;

Assets/SEE/CameraPaths/PathReplay.cs

@@ -71,8 +71,8 @@ public class PathReplay : MonoBehaviour
         /// as a serialized list of doubles (position.x, position.y,
         /// position.z, time for each entry in the path).
         /// </summary>
-        /// <param name="path">path to be serialized</param>
-        /// <returns>serialized position and timing data of path</returns>
+        /// <param name="path">Path to be serialized.</param>
+        /// <returns>Serialized position and timing data of path.</returns>
         private static IList<double> VectorsToList(CameraPath path)
         {
             List<double> list = new List<double>();
@@ -89,9 +89,9 @@ private static IList<double> VectorsToList(CameraPath path)
         /// <summary>
         /// Deserializes the list of doubles as list of Vector4s.
         /// </summary>
-        /// <param name="list">list to be deserialized</param>
-        /// <returns>list of Vectors4 (x,y,z,w) where x,y,z are
-        /// 3D co-ordinates and w is the time deserialized from given list</returns>
+        /// <param name="list">List to be deserialized.</param>
+        /// <returns>List of Vectors4 (x,y,z,w) where x,y,z are
+        /// 3D co-ordinates and w is the time deserialized from given list.</returns>
         private static Vector4[] ListToVectors(IList<double> list)
         {
             int num = list.Count / 4;
@@ -181,8 +181,8 @@ private void Start()
         /// <summary>
         /// Activate (true)/deactivates (false) <paramref name="parent"/> and all its descendants.
         /// </summary>
-        /// <param name="parent">root of the game-object tree</param>
-        /// <param name="activate">whether the game objects should be activated or deactivated</param>
+        /// <param name="parent">Root of the game-object tree.</param>
+        /// <param name="activate">Whether the game objects should be activated or deactivated.</param>
         private static void Activate(GameObject parent, bool activate)
         {
             parent.SetActive(activate);
@@ -222,10 +222,10 @@ private void Update()
         ///
         /// Increases the current index to the next point reached (but not farther than path.Count-1).
         /// </summary>
-        /// <param name="current">the current index into the path; will be increased to the
-        /// next index we need to reach at the given point in time</param>
-        /// <param name="time">current point in time since game start</param>
-        /// <returns>the interpolated rotation on the way between two subsequent path points</returns>
+        /// <param name="current">The current index into the path; will be increased to the
+        /// next index we need to reach at the given point in time.</param>
+        /// <param name="time">Current point in time since game start.</param>
+        /// <returns>The interpolated rotation on the way between two subsequent path points.</returns>
         private Quaternion Forward(ref int current, float time)
         {
             while (current < path.Count && path[current].Time < time)

Assets/SEE/Controls/Actions/AbstractPlayerAction.cs

@@ -59,7 +59,7 @@ public virtual void Redo()
         /// <summary>
         /// Returns the <see cref="ActionStateType"/> of the specific action.
         /// </summary>
-        /// <returns>the <see cref="ActionStateType"/> of the specific action</returns>
+        /// <returns>The <see cref="ActionStateType"/> of the specific action.</returns>
         public abstract ActionStateType GetActionStateType();
 
         /// <summary>
@@ -86,13 +86,13 @@ public virtual void Start()
         /// Will be called upon every frame when this action is being executed.
         /// See <see cref="IReversibleAction.Update"/>.
         /// </summary>
-        /// <returns>true if action is completed</returns>
+        /// <returns>True if action is completed.</returns>
         public abstract bool Update();
 
         /// <summary>
         /// Returns a new instance of the same type as this particular type of ReversibleAction.
         /// </summary>
-        /// <returns>new instance</returns>
+        /// <returns>New instance.</returns>
         public abstract IReversibleAction NewInstance();
 
         /// <summary>
@@ -109,7 +109,7 @@ public virtual void Stop()
         /// Sets <see cref="HoveredObject"/> to given <paramref name="interactableObject"/>.
         /// Will be called while any <see cref="InteractableObject"/> is being hovered over.
         /// </summary>
-        /// <param name="interactableObject">new value for <see cref="HoveredObject"/></param>
+        /// <param name="interactableObject">New value for <see cref="HoveredObject"/>.</param>
         protected void LocalAnyHoverIn(InteractableObject interactableObject)
         {
             HoveredObject = interactableObject.gameObject;
@@ -119,7 +119,7 @@ protected void LocalAnyHoverIn(InteractableObject interactableObject)
         /// Sets <see cref="HoveredObject"/> to <code>null</code>.
         /// Will be called whenever any <see cref="InteractableObject"/> is no longer being hovered over.
         /// </summary>
-        /// <param name="interactableObject">object no longer be hovered over (ignored here)</param>
+        /// <param name="interactableObject">Object no longer be hovered over (ignored here).</param>
         protected void LocalAnyHoverOut(InteractableObject interactableObject)
         {
             HoveredObject = null;
@@ -130,19 +130,19 @@ protected void LocalAnyHoverOut(InteractableObject interactableObject)
         /// that may need to be undone and whether it is still ongoing.
         /// Implements <see cref="IReversibleAction.CurrentProgress"/>.
         /// </summary>
-        /// <returns>the current state of the action</returns>
+        /// <returns>The current state of the action.</returns>
         public IReversibleAction.Progress CurrentProgress() => CurrentState;
 
         /// <summary>
         /// Returns the IDs of all gameObjects manipulated by the specific action.
         /// </summary>
-        /// <returns>All IDs of manipulated gameObjects</returns>
+        /// <returns>All IDs of manipulated gameObjects.</returns>
         public abstract HashSet<string> GetChangedObjects();
 
         /// <summary>
         /// A getter for the ID of this action.
         /// </summary>
-        /// <returns>The ID of this action as a string</returns>
+        /// <returns>The ID of this action as a string.</returns>
         public string GetId() => id.ToString();
     }
 }