In-code Documentation Update

* Addresses requests in SFML#194 and SFML#195
* Updated all [Obsolete] attributes to be less repetitive
* Added a large number of quick reference links to existing summaries
* Corrected various typos and unparsable markup(\a and \p)
* Added additional formatting to numerous summaries, resulting in more readable tooltips
* Added a suggestion to use TimeSpan over SFML's Time while working within a managed environment
* Added a warning to `VertexBuffer.NativeHandle`'s getter informing the end-user that most people shouldn't need that property and to be cautious

src/SFML.Graphics/PrimitiveType.cs

@@ -4,46 +4,48 @@ namespace SFML.Graphics
 {
     ////////////////////////////////////////////////////////////
     /// <summary>
-    /// Types of primitives that a VertexArray can render.
+    /// Types of primitives that a <see cref="VertexArray"/> or <see cref="VertexBuffer"/> can render.
+    /// </summary>
     ///
+    /// <remarks>
     /// Points and lines have no area, therefore their thickness
     /// will always be 1 pixel, regardless the current transform
     /// and view.
-    /// </summary>
+    /// </remarks>
     ////////////////////////////////////////////////////////////
     public enum PrimitiveType
     {
-        /// List of individual points
+        /// <summary>Individual Points</summary>
         Points,
 
-        /// List of individual lines
+        /// <summary>Individual, Disconnected Lines; each pair of points forms a line</summary>
         Lines,
 
-        /// List of connected lines, a point uses the previous point to form a line
+        /// <summary>Connected Lines; each point starts at the previous point to form a line</summary>
         LineStrip,
 
-        /// List of individual triangles
+        /// <summary>Individual, Disconnected Triangles</summary>
         Triangles,
 
-        /// List of connected triangles, a point uses the two previous points to form a triangle
+        /// <summary>Connected Triangles; each point uses the two previous points to form a triangle</summary>
         TriangleStrip,
 
-        /// List of connected triangles, a point uses the common center and the previous point to form a triangle
+        /// <summary>Connected Triangles; each point uses the first point and the previous point to form a triangle</summary>
         TriangleFan,
 
-        /// List of individual quads
+        /// <summary>Quadrilaterals; each set of four points forms a 4-sided shape</summary>
         Quads,
 
-        /// List of connected lines, a point uses the previous point to form a line
-        [Obsolete("LinesStrip is deprecated, please use LineStrip")]
+        /// <summary><c>DEPRECATED:</c> Use <see cref="LineStrip">LineStrip</see></summary>
+        [Obsolete("LineStrip")]
         LinesStrip = LineStrip,
 
-        /// List of connected triangles, a point uses the two previous points to form a triangle
-        [Obsolete("TrianglesStrip is deprecated, please use TriangleStrip")]
+        /// <summary><c>DEPRECATED:</c> Use <see cref="TriangleStrip">TriangleStrip</see></summary>
+        [Obsolete("Use TriangleStrip")]
         TrianglesStrip = TriangleStrip,
 
-        /// List of connected triangles, a point uses the common center and the previous point to form a triangle
-        [Obsolete("TrianglesFan is deprecated, please use TriangleFan")]
+        /// <summary><c>DEPRECATED:</c> Use <see cref="TriangleFan">TriangleFan</see></summary>
+        [Obsolete("Use TriangleFan")]
         TrianglesFan = TriangleFan,
     }
 }

src/SFML.Graphics/RenderTexture.cs

@@ -34,7 +34,7 @@ public RenderTexture(uint width, uint height) :
         /// <param name="height">Height of the render-texture</param>
         /// <param name="depthBuffer">Do you want a depth-buffer attached?</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("Creating a RenderTexture with depthBuffer is deprecated. Use RenderTexture(width, height, contextSettings) instead.")]
+        [Obsolete("Use RenderTexture(width, height, contextSettings)")]
         public RenderTexture(uint width, uint height, bool depthBuffer) :
             base(sfRenderTexture_create(width, height, depthBuffer))
         {
@@ -525,8 +525,7 @@ protected override void Destroy(bool disposing)
         private Texture myTexture = null;
 
         #region Imports
-        [Obsolete("sfRenderTexture_create is obselete. Use sfRenderTexture_createWithSettings instead.")]
-        [DllImport(CSFML.graphics, CallingConvention = CallingConvention.Cdecl), SuppressUnmanagedCodeSecurity]
+        [DllImport(CSFML.graphics, CallingConvention = CallingConvention.Cdecl), SuppressUnmanagedCodeSecurity, Obsolete]
         private static extern IntPtr sfRenderTexture_create(uint Width, uint Height, bool DepthBuffer);
 
         [DllImport(CSFML.graphics, CallingConvention = CallingConvention.Cdecl), SuppressUnmanagedCodeSecurity]

src/SFML.Graphics/RenderWindow.cs

@@ -678,7 +678,7 @@ public void ResetGLStates()
         ///    </code>
         /// </remarks>
         ////////////////////////////////////////////////////////////
-        [Obsolete("Capture is deprecated, please see remarks for preferred method")]
+        [Obsolete("Use Texture and Texture.Update(RenderWindow)")]
         public Image Capture()
         {
             return new Image(sfRenderWindow_capture(CPointer));

src/SFML.Graphics/Shader.cs

@@ -498,7 +498,7 @@ public unsafe void SetUniformArray(string name, Glsl.Mat4[] array)
         /// <param name="x">Value to assign</param>
         ///
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, float x)
         {
             sfShader_setFloatParameter(CPointer, name, x);
@@ -516,7 +516,7 @@ public void SetParameter(string name, float x)
         /// <param name="x">First component of the value to assign</param>
         /// <param name="y">Second component of the value to assign</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, float x, float y)
         {
             sfShader_setFloat2Parameter(CPointer, name, x, y);
@@ -535,7 +535,7 @@ public void SetParameter(string name, float x, float y)
         /// <param name="y">Second component of the value to assign</param>
         /// <param name="z">Third component of the value to assign</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, float x, float y, float z)
         {
             sfShader_setFloat3Parameter(CPointer, name, x, y, z);
@@ -555,7 +555,7 @@ public void SetParameter(string name, float x, float y, float z)
         /// <param name="z">Third component of the value to assign</param>
         /// <param name="w">Fourth component of the value to assign</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, float x, float y, float z, float w)
         {
             sfShader_setFloat4Parameter(CPointer, name, x, y, z, w);
@@ -572,7 +572,7 @@ public void SetParameter(string name, float x, float y, float z, float w)
         /// <param name="name">Name of the parameter in the shader</param>
         /// <param name="vector">Vector to assign</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, Vector2f vector)
         {
             SetParameter(name, vector.X, vector.Y);
@@ -589,7 +589,7 @@ public void SetParameter(string name, Vector2f vector)
         /// <param name="name">Name of the parameter in the shader</param>
         /// <param name="color">Color to assign</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, Color color)
         {
             sfShader_setColorParameter(CPointer, name, color);
@@ -606,7 +606,7 @@ public void SetParameter(string name, Color color)
         /// <param name="name">Name of the parameter in the shader</param>
         /// <param name="transform">Transform to assign</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, Transform transform)
         {
             sfShader_setTransformParameter(CPointer, name, transform);
@@ -630,7 +630,7 @@ public void SetParameter(string name, Transform transform)
         /// <param name="name">Name of the texture in the shader</param>
         /// <param name="texture">Texture to assign</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, Texture texture)
         {
             // Keep a reference to the Texture so it doesn't get GC'd
@@ -652,7 +652,7 @@ public void SetParameter(string name, Texture texture)
         /// <param name="name">Name of the texture in the shader</param>
         /// <param name="current">Always pass the spacial value Shader.CurrentTexture</param>
         ////////////////////////////////////////////////////////////
-        [Obsolete("SetParameter is deprecated, please use the corresponding SetUniform")]
+        [Obsolete("Use SetUniform()")]
         public void SetParameter(string name, CurrentTextureType current)
         {
             sfShader_setCurrentTextureParameter(CPointer, name);

src/SFML.Graphics/Text.cs

@@ -18,25 +18,25 @@ public class Text : Transformable, Drawable
     {
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Enumerate the string drawing styles
+        /// Flags for styles that can be applied to the <see cref="Text"/>
         /// </summary>
         ////////////////////////////////////////////////////////////
         [Flags]
         public enum Styles
         {
-            /// <summary>Regular characters, no style</summary>
+            /// <summary>No Style</summary>
             Regular = 0,
 
-            /// <summary>Bold characters</summary>
+            /// <summary>Bold</summary>
             Bold = 1 << 0,
 
-            /// <summary>Italic characters</summary>
+            /// <summary>Italic</summary>
             Italic = 1 << 1,
 
-            /// <summary>Underlined characters</summary>
+            /// <summary>Underlined</summary>
             Underlined = 1 << 2,
 
-            /// <summary>Strike through characters</summary>
+            /// <summary>Strikethrough</summary>
             StrikeThrough = 1 << 3
         }
 
@@ -52,7 +52,7 @@ public Text() :
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Construct the text from a string and a font
+        /// Construct the text from a string and a <see cref="SFML.Graphics.Font"/>
         /// </summary>
         /// <param name="str">String to display</param>
         /// <param name="font">Font to use</param>
@@ -64,11 +64,11 @@ public Text(string str, Font font) :
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Construct the text from a string, font and size
+        /// Construct the text from a string, <see cref="SFML.Graphics.Font"/> and size
         /// </summary>
         /// <param name="str">String to display</param>
         /// <param name="font">Font to use</param>
-        /// <param name="characterSize">Base characters size</param>
+        /// <param name="characterSize">Font size</param>
         ////////////////////////////////////////////////////////////
         public Text(string str, Font font, uint characterSize) :
             base(sfText_create())
@@ -80,7 +80,7 @@ public Text(string str, Font font, uint characterSize) :
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Construct the text from another text
+        /// Construct the text from another <see cref="SFML.Graphics.Text"/>
         /// </summary>
         /// <param name="copy">Text to copy</param>
         ////////////////////////////////////////////////////////////
@@ -97,18 +97,20 @@ public Text(Text copy) :
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Fill color of the object
+        /// DEPRECATED Fill <see cref="SFML.Graphics.Color"/> of the <see cref="Text"/>
         /// </summary>
         /// 
         /// <remarks>
-        /// Deprecated. Use <see cref="FillColor"/> instead.
+        /// Use <see cref="FillColor"/> instead.
         /// 
-        /// By default, the text's fill color is opaque white.
-        /// Setting the fill color to a transparent color with an outline
-        /// will cause the outline to be displayed in the fill area of the text.
+        /// By default, the text's fill <see cref="SFML.Graphics.Color"/> is <see cref="SFML.Graphics.Color.White">opaque White</see>.
+        /// <para>
+        /// Setting the fill color to a transparent <see cref="SFML.Graphics.Color"/> with an outline
+        /// will cause the outline to be displayed in the fill area of the text.
+        /// </para>
         /// </remarks>
         ////////////////////////////////////////////////////////////
-        [Obsolete]
+        [Obsolete("Use FillColor and OutlineColor")]
         public Color Color
         {
             get { return sfText_getFillColor(CPointer); }
@@ -117,13 +119,15 @@ public Color Color
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Fill color of the object
+        /// Fill <see cref="SFML.Graphics.Color"/> of the <see cref="Text"/>
         /// </summary>
         /// 
         /// <remarks>
-        /// By default, the text's fill color is opaque white.
-        /// Setting the fill color to a transparent color with an outline
-        /// will cause the outline to be displayed in the fill area of the text.
+        /// By default, the text's fill <see cref="SFML.Graphics.Color"/> is <see cref="SFML.Graphics.Color.White">opaque White</see>.
+        /// <para>
+        /// Setting the fill color to a transparent <see cref="SFML.Graphics.Color"/> with an outline
+        /// will cause the outline to be displayed in the fill area of the text.
+        /// </para>
         /// </remarks>
         ////////////////////////////////////////////////////////////
         public Color FillColor
@@ -134,11 +138,11 @@ public Color FillColor
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Outline color of the object
+        /// Outline <see cref="SFML.Graphics.Color"/> of the <see cref="Text"/>
         /// </summary>
         /// 
         /// <remarks>
-        /// By default, the text's outline color is opaque black.
+        /// By default, the text's outline <see cref="SFML.Graphics.Color"/> is <see cref="SFML.Graphics.Color.Black">opaque Black</see>.
         /// </remarks>
         ////////////////////////////////////////////////////////////
         public Color OutlineColor
@@ -212,7 +216,7 @@ public string DisplayedString
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Font used to display the text
+        /// <see cref="SFML.Graphics.Font"/> used to display the text
         /// </summary>
         ////////////////////////////////////////////////////////////
         public Font Font
@@ -256,7 +260,7 @@ public float LineSpacing
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Style of the text (see Styles enum)
+        /// <see cref="Styles">Style</see> of the text
         /// </summary>
         ////////////////////////////////////////////////////////////
         public Styles Style
@@ -268,9 +272,11 @@ public Styles Style
         ////////////////////////////////////////////////////////////
         /// <summary>
         /// Return the visual position of the Index-th character of the text,
-        /// in coordinates relative to the text
-        /// (note : translation, origin, rotation and scale are not applied)
-        /// </summary>
+        /// in coordinates relative to the text
+        /// </summary>
+        /// <remarks>
+        /// Translation, origin, rotation and scale are not applied.
+        /// </remarks>
         /// <param name="index">Index of the character</param>
         /// <returns>Position of the Index-th character (end of text if Index is out of range)</returns>
         ////////////////////////////////////////////////////////////
@@ -281,14 +287,14 @@ public Vector2f FindCharacterPos(uint index)
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Get the local bounding rectangle of the entity.
-        ///
-        /// The returned rectangle is in local coordinates, which means
-        /// that it ignores the transformations (translation, rotation,
-        /// scale, ...) that are applied to the entity.
-        /// In other words, this function returns the bounds of the
-        /// entity in the entity's coordinate system.
+        /// Get the local bounding <see cref="FloatRect"/> of the text.
         /// </summary>
+        /// <remarks>
+        /// The returned <see cref="FloatRect"/> is in local coordinates.
+        /// <para>Transformations (Translation, Rotation, Scale) are not applied to the entity.</para>
+        /// <para>In other words, this function returns the bounds of the
+        /// entity in the entity's coordinate system.</para>
+        /// </remarks>
         /// <returns>Local bounding rectangle of the entity</returns>
         ////////////////////////////////////////////////////////////
         public FloatRect GetLocalBounds()
@@ -298,14 +304,14 @@ public FloatRect GetLocalBounds()
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Get the global bounding rectangle of the entity.
-        ///
-        /// The returned rectangle is in global coordinates, which means
-        /// that it takes in account the transformations (translation,
-        /// rotation, scale, ...) that are applied to the entity.
-        /// In other words, this function returns the bounds of the
-        /// sprite in the global 2D world's coordinate system.
+        /// Get the global bounding rectangle of the text.
         /// </summary>
+        /// <remarks>
+        /// The returned <see cref="FloatRect"/> is in global coordinates.
+        /// <para>Transformations (Translation, Rotation, Scale) are applied to the entity.</para>
+        /// <para>In other words, this function returns the bounds of the
+        /// sprite in the global 2D world's coordinate system.</para>
+        /// </remarks>
         /// <returns>Global bounding rectangle of the entity</returns>
         ////////////////////////////////////////////////////////////
         public FloatRect GetGlobalBounds()
@@ -335,7 +341,7 @@ public override string ToString()
 
         ////////////////////////////////////////////////////////////
         /// <summary>
-        /// Draw the text to a render target
+        /// Draw the text to a <see cref="RenderTarget"/>
         /// </summary>
         /// <param name="target">Render target to draw to</param>
         /// <param name="states">Current render states</param>

src/SFML.Graphics/Texture.cs

@@ -18,6 +18,9 @@ public class Texture : ObjectBase
         /// <summary>
         /// Construct the texture
         /// </summary>
+        /// <remarks>
+        /// Textures created this way are uninitialized and have indeterminate contents.
+        /// </remarks>
         /// <param name="width">Texture width</param>
         /// <param name="height">Texture height</param>
         /// <exception cref="LoadingFailedException" />