Documentation

BansheeCore/Include/BsFont.h

@@ -103,6 +103,6 @@ namespace BansheeEngine
 	public:
 		friend class FontRTTI;
 		static RTTITypeBase* getRTTIStatic();
-		virtual RTTITypeBase* getRTTI() const;
+		virtual RTTITypeBase* getRTTI() const override;
 	};
 }

BansheeCore/Include/BsInput.h

@@ -145,7 +145,7 @@ namespace BansheeEngine
 		bool isButtonHeld(ButtonCode keyCode, UINT32 deviceIdx = 0) const;
 
 		/**
-		 * @brief	Query if the provided button is currently being released (one true for one frame).
+		 * @brief	Query if the provided button is currently being released (only true for one frame).
 		 *
 		 * @param	keyCode		Code of the button to query.
 		 * @param	deviceIdx	Device to query the button on (0 - primary).
@@ -153,7 +153,7 @@ namespace BansheeEngine
 		bool isButtonUp(ButtonCode keyCode, UINT32 deviceIdx = 0) const;
 
 		/**
-		 * @brief	Query if the provided button is currently being pressed (one true for one frame).
+		 * @brief	Query if the provided button is currently being pressed (only true for one frame).
 		 *
 		 * @param	keyCode		Code of the button to query.
 		 * @param	deviceIdx	Device to query the button on (0 - primary).
@@ -161,7 +161,7 @@ namespace BansheeEngine
 		bool isButtonDown(ButtonCode keyCode, UINT32 deviceIdx = 0) const;
 
 		/**
-		 * @brief	Returns positions of the pointer (e.g. mouse cursor) relative to the screen.
+		 * @brief	Returns position of the pointer (e.g. mouse cursor) relative to the screen.
 		 */
 		Vector2I getPointerPosition() const;
 
@@ -180,7 +180,7 @@ namespace BansheeEngine
 
 		/**
 		 * @brief	Query if the provided pointer button is currently 
-		 *			being released (one true for one frame).
+		 *			being released (only true for one frame).
 		 *
 		 * @param	pointerButton		Code of the button to query.
 		 */
@@ -188,14 +188,14 @@ namespace BansheeEngine
 
 		/**
 		 * @brief	Query if the provided pointer button is currently 
-		 *			being pressed (one true for one frame).
+		 *			being pressed (only true for one frame).
 		 *
 		 * @param	pointerButton		Code of the button to query.
 		 */
 		bool isPointerButtonDown(PointerEventButton pointerButton) const;
 
 		/**
-		 * @brief	Query if the provided the left pointer button has been 
+		 * @brief	Query has the left pointer button has been 
 		 *			double-clicked this frame.
 		 */
 		bool isPointerDoubleClicked() const;

BansheeCore/Include/BsInputFwd.h

@@ -232,7 +232,7 @@ namespace BansheeEngine
 	};
 
 	/**
-	 * @brief	Structure containing information about a button input event.
+	 * @brief	Contains data about a button input event.
 	 */
 	struct ButtonEvent
 	{
@@ -243,7 +243,7 @@ namespace BansheeEngine
 
 		ButtonCode buttonCode; /**< Button code this event is referring to. */
 		UINT64 timestamp; /**< Timestamp in ticks when the event happened. */
-		UINT32 deviceIdx; /**< Index of the device that the event happened on. */
+		UINT32 deviceIdx; /**< Index of the device that the event originated from. */
 
 		/**
 		 * @brief	Query is the pressed button a keyboard button.
@@ -318,11 +318,11 @@ namespace BansheeEngine
 										depending on event type. (e.g. move events don't correspond to a button. */
 		PointerEventType type; /**< Type of the pointer event. */
 
-		bool shift; /**< Is Shift button on the keyboard being held down. */
-		bool control; /**< Is Control button on the keyboard being held down. */
-		bool alt; /**< Is Alt button on the keyboard being held down. */
+		bool shift; /**< Is shift button on the keyboard being held down. */
+		bool control; /**< Is control button on the keyboard being held down. */
+		bool alt; /**< Is alt button on the keyboard being held down. */
 
-		float mouseWheelScrollAmount; /**< If mouse wheel is being scrolled, what is the amount. Only relevant on move events. */
+		float mouseWheelScrollAmount; /**< If mouse wheel is being scrolled, what is the amount. Only relevant for move events. */
 
 		/**
 		 * @brief	Check if the event has been marked as used. Internally this means nothing
@@ -361,7 +361,7 @@ namespace BansheeEngine
 			:mIsUsed(false)
 		{ }
 
-		UINT32 textChar; /**< Character the user is inputting. */
+		UINT32 textChar; /**< Character the that was input. */
 
 		/**
 		 * @brief	Check if the event has been marked as used. Internally this means nothing

MBansheeEngine/DontSerializeField.cs

@@ -2,6 +2,11 @@
 
 namespace BansheeEngine
 {
+    /// <summary>
+    /// Attribute that prevents serialization of a field that would otherwise be serialized. Normally those fields
+    /// are public fields of a <see cref="Component"/>, <see cref="Resource"/> or a class marked with a 
+    /// <see cref="SerializeObject"/> attribute.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Field)]
     public sealed class DontSerializeField : Attribute
     {

MBansheeEngine/FileEx.cs

@@ -2,8 +2,16 @@
 
 namespace BansheeEngine
 {
+    /// <summary>
+    /// Contains various methods that provide handling for files not provided by System.File type.
+    /// </summary>
     public static class FileEx
     {
+        /// <summary>
+        /// Moves a file from one path to another, while creating any parent directories if they don't already exist.
+        /// </summary>
+        /// <param name="source">Path to the file to move.</param>
+        /// <param name="destination">New location and/or name of the file.</param>
         public static void Move(string source, string destination)
         {
             string destParent = PathEx.GetParent(destination);
@@ -16,6 +24,11 @@ namespace BansheeEngine
             File.Move(source, destination);
         }
 
+        /// <summary>
+        /// Copies a file from one path to another, while creating any parent directories if they don't already exist.
+        /// </summary>
+        /// <param name="source">Path to the file to copy.</param>
+        /// <param name="destination">Path to the copied file.</param>
         public static void Copy(string source, string destination)
         {
             string destParent = PathEx.GetParent(destination);

MBansheeEngine/Font.cs

@@ -4,6 +4,9 @@ using System.Runtime.InteropServices;
 
 namespace BansheeEngine
 {
+    /// <summary>
+    /// Marks a range of characters in a font.
+    /// </summary>
     [StructLayout(LayoutKind.Sequential)]
     public struct CharRange
     {
@@ -11,8 +14,15 @@ namespace BansheeEngine
         public UInt32 end;
     }
 
+    /// <summary>
+    /// Font resource containing data about textual characters and how to render text.
+    /// </summary>
     public sealed class Font : Resource // TODO - Dummy class
     {
+        /// <summary>
+        /// Creates a new font resource. For runtime use only.
+        /// </summary>
+        /// <param name="constructNative">Should the constructor also create the native interop object.</param>
         internal Font(bool constructNative)
         {
             if (constructNative)

MBansheeEngine/GameObject.cs

@@ -3,8 +3,14 @@ using System.Runtime.CompilerServices;
 
 namespace BansheeEngine
 {
+    /// <summary>
+    /// A base class for objects that can be part of the scene and referenced by other game objects.
+    /// </summary>
     public class GameObject : ScriptObject
     {
+        /// <summary>
+        /// Returns a unique ID for the game object.
+        /// </summary>
         public UInt64 InstanceId
         {
             get { return Internal_GetInstanceId(mCachedPtr); }

MBansheeEngine/HideInInspector.cs

@@ -2,6 +2,11 @@
 
 namespace BansheeEngine
 {
+    /// <summary>
+    /// Attribute that prevents a field from being visible in the inspector window in editor. Normally those fields
+    /// are public fields of a <see cref="Component"/>, <see cref="Resource"/> or a class marked with a 
+    /// <see cref="SerializeObject"/> attribute.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Field)]
     public sealed class HideInInspector : Attribute
     {

MBansheeEngine/Input.cs

@@ -6,31 +6,63 @@ using System.Text;
 
 namespace BansheeEngine
 {
+    /// <summary>
+    /// Contains data about a button input event.
+    /// </summary>
 	public struct ButtonEvent
 	{
 		internal ButtonCode buttonCode;
         internal int deviceIdx;
 
+        /// <summary>
+        /// Creates a new button input event. For runtime use only.
+        /// </summary>
+        /// <param name="buttonCode">Button code this event is referring to.</param>
+        /// <param name="deviceIdx">Index of the device that the event originated from.</param>
 	    internal ButtonEvent(ButtonCode buttonCode, int deviceIdx)
 	    {
 	        this.buttonCode = buttonCode;
 	        this.deviceIdx = deviceIdx;
 	    }
 
+        /// <summary>
+        /// Button code this event is referring to.
+        /// </summary>
         public ButtonCode Button { get { return buttonCode; } }
+
+        /// <summary>
+        /// Index of the device that the event originated from.
+        /// </summary>
         public int DeviceIndex { get { return deviceIdx; } }
 
+        /// <summary>
+        /// Query is the pressed button a keyboard button.
+        /// </summary>
 		public bool IsKeyboard { get { return ((int)buttonCode & 0xC0000000) == 0; }}
+
+        /// <summary>
+        /// Query is the pressed button a mouse button.
+        /// </summary>
         public bool IsMouse { get { return ((int)buttonCode & 0x80000000) != 0; } }
+
+        /// <summary>
+        /// Query is the pressed button a gamepad button.
+        /// </summary>
         public bool IsGamepad { get { return ((int)buttonCode & 0x40000000) != 0; } }
 	};
 
-    // Do not change IDs, must match PointerEventButton C++ enum
-	public enum PointerButton
+    /// <summary>
+    /// Pointer buttons. Generally these correspond to mouse buttons, but may be used in some form for touch input as well.
+    /// </summary>
+    public enum PointerButton // Note: Must match C++ enum PointerEventButton 
 	{
 		Left, Middle, Right, Count
 	};
 
+    /// <summary>
+    /// Event that gets sent out when user interacts with the screen in some way, usually by moving the mouse cursor or 
+    /// using touch input.
+    /// </summary>
     public struct PointerEvent
     {
         internal Vector2I _screenPos;
@@ -43,6 +75,18 @@ namespace BansheeEngine
 
         internal float _mouseWheelScrollAmount;
 
+        /// <summary>
+        /// Creates a new pointer event. For runtime use only.
+        /// </summary>
+        /// <param name="screenPos">Screen position where the input event occurred.</param>
+        /// <param name="delta">Change in movement since last sent event.</param>
+        /// <param name="button">Button that triggered the pointer event. Might be irrelevant depending on event type. 
+        ///                      (e.g. move events don't correspond to a button.</param>
+        /// <param name="shift">Is shift button on the keyboard being held down.</param>
+        /// <param name="control">Is control button on the keyboard being held down.</param>
+        /// <param name="alt">Is alt button on the keyboard being held down.</param>
+        /// <param name="mouseWheelScrollAmount">If mouse wheel is being scrolled, what is the amount. Only relevant for 
+        ///                                      move events.</param>
         internal PointerEvent(Vector2I screenPos, Vector2I delta, PointerButton button,
             bool shift, bool control, bool alt, float mouseWheelScrollAmount)
         {
@@ -57,29 +101,69 @@ namespace BansheeEngine
             _mouseWheelScrollAmount = mouseWheelScrollAmount;
         }
 
+        /// <summary>
+        /// Screen position where the input event occurred.
+        /// </summary>
         public Vector2I ScreenPos { get { return _screenPos; } }
+
+        /// <summary>
+        /// Change in movement since last sent event.
+        /// </summary>
         public Vector2I Delta { get { return _delta; } }
+
+        /// <summary>
+        /// Button that triggered the pointer event. Might be irrelevant depending on event type. 
+        /// (e.g. move events don't correspond to a button.
+        /// </summary>
         public PointerButton Button { get { return _button; } }
 
+        /// <summary>
+        /// Is shift button on the keyboard being held down.
+        /// </summary>
         public bool Shift { get { return _shift; } }
+
+        /// <summary>
+        /// Is control button on the keyboard being held down.
+        /// </summary>
         public bool Control { get { return _control; } }
+
+        /// <summary>
+        /// Is alt button on the keyboard being held down.
+        /// </summary>
         public bool Alt { get { return _alt; } }
 
+        /// <summary>
+        /// If mouse wheel is being scrolled, what is the amount. Only relevant for move events.
+        /// </summary>
         public float ScrollAmount { get { return _mouseWheelScrollAmount; } }
     }
 
+    /// <summary>
+    /// Event that gets sent out when user inputs some text. These events may be preceeded by normal button events if user 
+    /// is typing on a keyboard.
+    /// </summary>
     public struct TextInputEvent
     {
         internal int textChar;
 
+        /// <summary>
+        /// Creates a new text input event. For runtime use only.
+        /// </summary>
+        /// <param name="textChar">Character the that was input.</param>
         internal TextInputEvent(int textChar)
         {
             this.textChar = textChar;
         }
 
+        /// <summary>
+        /// Character the that was input.
+        /// </summary>
         public int Char { get { return textChar; } }
     }
 
+    /// <summary>
+    /// Allows you to query and receive events from all connected input devices.
+    /// </summary>
     public static class Input
     {
         public delegate void ButtonEventDelegate(ButtonEvent ev);
@@ -94,46 +178,93 @@ namespace BansheeEngine
         public static event PointerEventDelegate OnPointerReleased;
         public static event PointerEventDelegate OnPointerDoubleClick;
 
+        /// <summary>
+        /// Returns value of the specified input axis. 
+        /// </summary>
+        /// <param name="axis">Type of axis to query.</param>
+        /// <param name="deviceIdx">Index of the device in case more than one is hooked up (0 - primary).</param>
+        /// <returns>Value of the axis in range [-1.0, 1.0]. Canan be outside the range for devices with unbound axes 
+        ///          (e.g. mouse).</returns>
         public static float GetAxisValue(InputAxis axis, int deviceIdx = 0)
         {
             return Internal_GetAxisValue(axis, deviceIdx);
         }
 
+        /// <summary>
+        /// Query if the provided button is currently being held (this frame or previous frames).
+        /// </summary>
+        /// <param name="code">Code of the button to query.</param>
+        /// <param name="deviceIdx">Device to query the button on (0 - primary).</param>
+        /// <returns>True if the button is held.</returns>
         public static bool IsButtonHeld(ButtonCode code, int deviceIdx = 0)
         {
             return Internal_IsButtonHeld(code, deviceIdx);
         }
 
+        /// <summary>
+        /// Query if the provided button is currently being released (only true for one frame).
+        /// </summary>
+        /// <param name="code">Code of the button to query.</param>
+        /// <param name="deviceIdx">Device to query the button on (0 - primary).</param>
+        /// <returns>True if the button is being released.</returns>
         public static bool IsButtonUp(ButtonCode code, int deviceIdx = 0)
         {
             return Internal_IsButtonUp(code, deviceIdx);
         }
 
+        /// <summary>
+        /// Query if the provided button is currently being pressed (only true for one frame).
+        /// </summary>
+        /// <param name="code">Code of the button to query.</param>
+        /// <param name="deviceIdx">Device to query the button on (0 - primary).</param>
+        /// <returns>True if the button is being pressed.</returns>
         public static bool IsButtonDown(ButtonCode code, int deviceIdx = 0)
         {
             return Internal_IsButtonDown(code, deviceIdx);
         }
 
+        /// <summary>
+        /// Query if the provided pointer button is currently being held (this frame or previous frames).
+        /// </summary>
+        /// <param name="code">Code of the button to query.</param>
+        /// <returns>True if the button is being held.</returns>
         public static bool IsPointerButtonHeld(PointerButton code)
         {
             return Internal_IsPointerButtonHeld(code);
         }
 
+        /// <summary>
+        /// Query if the provided pointer button is currently being being released (only true for one frame).
+        /// </summary>
+        /// <param name="code">Code of the button to query.</param>
+        /// <returns>True if the button is being released.</returns>
         public static bool IsPointerButtonUp(PointerButton code)
         {
             return Internal_IsPointerButtonUp(code);
         }
 
+        /// <summary>
+        /// Query if the provided pointer button is currently being being pressed (only true for one frame).
+        /// </summary>
+        /// <param name="code">Code of the button to query.</param>
+        /// <returns>True if the button is being pressed.</returns>
         public static bool IsPointerButtonDown(PointerButton code)
         {
             return Internal_IsPointerButtonDown(code);
         }
 
+        /// <summary>
+        /// Query has the left pointer button been double-clicked this frame.
+        /// </summary>
+        /// <returns>True if double-click occurred.</returns>
         public static bool IsPointerDoubleClicked()
         {
             return Internal_IsPointerDoubleClicked();
         }
 
+        /// <summary>
+        /// Returns position of the pointer (e.g. mouse cursor) relative to the screen.
+        /// </summary>
         public static Vector2I PointerPosition
         {
             get
@@ -144,6 +275,9 @@ namespace BansheeEngine
             }
         }
 
+        /// <summary>
+        /// Returns difference between last and current pointer position.
+        /// </summary>
         public static Vector2I PointerDelta
         {
             get
@@ -154,6 +288,11 @@ namespace BansheeEngine
             }
         }
 
+        /// <summary>
+        /// Triggered by runtime when a button is pressed.
+        /// </summary>
+        /// <param name="code">Code of the pressed button.</param>
+        /// <param name="deviceIdx">Device the event originated from.</param>
         private static void Internal_TriggerButtonDown(ButtonCode code, int deviceIdx)
         {
             ButtonEvent ev = new ButtonEvent(code, deviceIdx);
@@ -162,6 +301,11 @@ namespace BansheeEngine
                 OnButtonDown(ev);
         }
 
+        /// <summary>
+        /// Triggered by runtime when a button is released.
+        /// </summary>
+        /// <param name="code">Code of the released button.</param>
+        /// <param name="deviceIdx">Device the event originated from.</param>
         private static void Internal_TriggerButtonUp(ButtonCode code, int deviceIdx)
         {
             ButtonEvent ev = new ButtonEvent(code, deviceIdx);
@@ -170,6 +314,10 @@ namespace BansheeEngine
                 OnButtonUp(ev);
         }
 
+        /// <summary>
+        /// Triggered by runtime when character is input.
+        /// </summary>
+        /// <param name="textChar">Code of input character.</param>
         private static void Internal_TriggerCharInput(int textChar)
         {
             TextInputEvent ev = new TextInputEvent(textChar);
@@ -178,6 +326,18 @@ namespace BansheeEngine
                 OnCharInput(ev);
         }
 
+        /// <summary>
+        /// Triggers when some pointing device (mouse cursor, touch) moves.
+        /// </summary>
+        /// <param name="screenPos">Screen position where the input event occurred.</param>
+        /// <param name="delta">Change in movement since last sent event.</param>
+        /// <param name="button">Button that triggered the pointer event. Might be irrelevant depending on event type. 
+        ///                      (e.g. move events don't correspond to a button.</param>
+        /// <param name="shift">Is shift button on the keyboard being held down.</param>
+        /// <param name="ctrl">Is control button on the keyboard being held down.</param>
+        /// <param name="alt">Is alt button on the keyboard being held down.</param>
+        /// <param name="scrollAmount">If mouse wheel is being scrolled, what is the amount. Only relevant for 
+        ///                            move events.</param>
         private static void Internal_TriggerPointerMove(Vector2I screenPos, Vector2I delta, PointerButton button, bool shift, 
             bool ctrl, bool alt, float scrollAmount)
         {
@@ -187,6 +347,18 @@ namespace BansheeEngine
                 OnPointerMoved(ev);
         }
 
+        /// <summary>
+        /// Triggers when some pointing device (mouse cursor, touch) button is pressed.
+        /// </summary>
+        /// <param name="screenPos">Screen position where the input event occurred.</param>
+        /// <param name="delta">Change in movement since last sent event.</param>
+        /// <param name="button">Button that triggered the pointer event. Might be irrelevant depending on event type. 
+        ///                      (e.g. move events don't correspond to a button.</param>
+        /// <param name="shift">Is shift button on the keyboard being held down.</param>
+        /// <param name="ctrl">Is control button on the keyboard being held down.</param>
+        /// <param name="alt">Is alt button on the keyboard being held down.</param>
+        /// <param name="scrollAmount">If mouse wheel is being scrolled, what is the amount. Only relevant for 
+        ///                            move events.</param>
         private static void Internal_TriggerPointerPressed(Vector2I screenPos, Vector2I delta, PointerButton button, bool shift,
             bool ctrl, bool alt, float scrollAmount)
         {
@@ -196,6 +368,18 @@ namespace BansheeEngine
                 OnPointerPressed(ev);
         }
 
+        /// <summary>
+        /// Triggers when some pointing device (mouse cursor, touch) button is released.
+        /// </summary>
+        /// <param name="screenPos">Screen position where the input event occurred.</param>
+        /// <param name="delta">Change in movement since last sent event.</param>
+        /// <param name="button">Button that triggered the pointer event. Might be irrelevant depending on event type. 
+        ///                      (e.g. move events don't correspond to a button.</param>
+        /// <param name="shift">Is shift button on the keyboard being held down.</param>
+        /// <param name="ctrl">Is control button on the keyboard being held down.</param>
+        /// <param name="alt">Is alt button on the keyboard being held down.</param>
+        /// <param name="scrollAmount">If mouse wheel is being scrolled, what is the amount. Only relevant for 
+        ///                            move events.</param>
         private static void Internal_TriggerPointerReleased(Vector2I screenPos, Vector2I delta, PointerButton button, bool shift,
             bool ctrl, bool alt, float scrollAmount)
         {
@@ -205,6 +389,18 @@ namespace BansheeEngine
                 OnPointerReleased(ev);
         }
 
+        /// <summary>
+        /// Triggers when some pointing device (mouse cursor, touch) button is double clicked.
+        /// </summary>
+        /// <param name="screenPos">Screen position where the input event occurred.</param>
+        /// <param name="delta">Change in movement since last sent event.</param>
+        /// <param name="button">Button that triggered the pointer event. Might be irrelevant depending on event type. 
+        ///                      (e.g. move events don't correspond to a button.</param>
+        /// <param name="shift">Is shift button on the keyboard being held down.</param>
+        /// <param name="ctrl">Is control button on the keyboard being held down.</param>
+        /// <param name="alt">Is alt button on the keyboard being held down.</param>
+        /// <param name="scrollAmount">If mouse wheel is being scrolled, what is the amount. Only relevant for 
+        ///                            move events.</param>
         private static void Internal_TriggerPointerDoubleClick(Vector2I screenPos, Vector2I delta, PointerButton button, bool shift,
             bool ctrl, bool alt, float scrollAmount)
         {
@@ -245,8 +441,10 @@ namespace BansheeEngine
         private static extern void Internal_GetPointerDelta(out Vector2I delta);
     }
 
-    // Do not change IDs, must match ButtonCode C++ enum
-    public enum ButtonCode : uint
+    /// <summary>
+    /// Contains all possible input buttons, including keyboard scan codes, mouse buttons and gamepad buttons.
+    /// </summary>
+    public enum ButtonCode : uint // Note: Must match C++ enum ButtonCode
     {
         Unassigned = 0x00,
         Escape = 0x01,
@@ -410,8 +608,10 @@ namespace BansheeEngine
         NumGamepadButtons = 30,
     };
 
-    // Do not change IDs, must match InputAxis C++ enum
-	public enum InputAxis
+    /// <summary>
+    /// Available types of input axes.
+    /// </summary>
+	public enum InputAxis // Note: Must match C++ enum InputBox
 	{
 		MouseX,
 		MouseY,

TODO.txt

@@ -71,7 +71,6 @@ Other polish:
    - Possibly create helper objects: Cube, Sphere, Plane, Quad, Capsule, Cylinder
   - Help - About, API Reference (link to site)
  - New UI look
- - Replace "minimize" button in tabbed title bar with maximize and make sure it works (in both docked and floating mode)
  - When I expand inspector elements and them come back to that object it should remember the previous state
    - Add a chaching mechanism to inspector (likely based on instance ID & property names)
    - This has to work not only when I come back to the object, but whenever inspector rebuilds (e.g. after removing element from array)