Allow XML documentation to be generated for Pinta.Core.

This should be helpful for people building addins.
- Disabled warning 1591, which resulted in thousands of warnings about
every undocumented public member.
- Cleaned up a bunch of out-of-date documentation that was caught by the
compiler.

Pinta.Core/Classes/BaseTool.cs

@@ -280,7 +280,7 @@ public void SetCursor (Gdk.Cursor cursor)
 		/// <param name="shape">The shape to draw.</param>
 		/// <param name="shapeWidth">The width of the shape.</param>
 		/// <param name="imgToShapeX">The horizontal distance between the image's top-left corner and the shape center.</param>
-		/// <param name="imgToShapeX">The verical distance between the image's top-left corner and the shape center.</param>
+		/// <param name="imgToShapeY">The verical distance between the image's top-left corner and the shape center.</param>
 		/// <param name="shapeX">The X position in the returned Pixbuf that will be the center of the shape.</param>
 		/// <param name="shapeY">The Y position in the returned Pixbuf that will be the center of the shape.</param>
 		/// <returns>The new cursor icon with an shape that represents the tool's thickness.</returns>

Pinta.Core/Classes/Document.cs

@@ -613,6 +613,9 @@ public void ResetSelectionPath()
 		/// <summary>
 		/// Resizes the canvas.
 		/// </summary>
+		/// <param name="width">The new width of the canvas.</param>
+		/// <param name="height">The new height of the canvas.</param>
+		/// <param name="anchor">Direction in which to adjust the canvas</param>
 		/// <param name='compoundAction'>
 		/// Optionally, the history item for resizing the canvas can be added to
 		/// a CompoundHistoryItem if it is part of a larger action (e.g. pasting an image).

Pinta.Core/Classes/DocumentSelection.cs

@@ -403,6 +403,9 @@ public void CreateRectangleSelection(Surface selectionSurface, Rectangle r)
 		/// <summary>
 		/// Inverts the selection.
 		/// </summary>
+		/// <param name="surface">
+		/// Surface for the selection path.
+		/// </param>
 		/// <param name='imageSize'>
 		/// The size of the document.
 		/// </param>

Pinta.Core/Clipper/Clipper.cs

@@ -1,60 +1,57 @@
-/*******************************************************************************
-*                                                                              *
-* Author    :  Angus Johnson                                                   *
-* Version   :  4.8.4                                                           *
-* Date      :  1 June 2012                                                     *
-* Website   :  http://www.angusj.com                                           *
-* Copyright :  Angus Johnson 2010-2012                                         *
-*                                                                              *
-* License:                                                                     *
-* Use, modification & distribution is subject to Boost Software License Ver 1. *
-* http://www.boost.org/LICENSE_1_0.txt                                         *
-*                                                                              *
-* Attributions:                                                                *
-* The code in this library is an extension of Bala Vatti's clipping algorithm: *
-* "A generic solution to polygon clipping"                                     *
-* Communications of the ACM, Vol 35, Issue 7 (July 1992) pp 56-63.             *
-* http://portal.acm.org/citation.cfm?id=129906                                 *
-*                                                                              *
-* Computer graphics and geometric modeling: implementation and algorithms      *
-* By Max K. Agoston                                                            *
-* Springer; 1 edition (January 4, 2005)                                        *
-* http://books.google.com/books?q=vatti+clipping+agoston                       *
-*                                                                              *
-* See also:                                                                    *
-* "Polygon Offsetting by Computing Winding Numbers"                            *
-* Paper no. DETC2005-85513 pp. 565-575                                         *
-* ASME 2005 International Design Engineering Technical Conferences             *
-* and Computers and Information in Engineering Conference (IDETC/CIE2005)      *
-* September 24–28, 2005 , Long Beach, California, USA                          *
-* http://www.me.berkeley.edu/~mcmains/pubs/DAC05OffsetPolygon.pdf              *
-*                                                                              *
-*******************************************************************************/
-
-/*******************************************************************************
-*                                                                              *
-* This is a translation of the Delphi Clipper library and the naming style     *
-* used has retained a Delphi flavour.                                          *
-*                                                                              *
-*******************************************************************************/
-
-/*
- * This Clipper Library code was imported into Pinta on June 6th, 2012 by
- * Andrew Davis of GSoC 2012 for the MagicWandTool selection modes
- * implementation. It calculates "boolean clipping operations" (union,
- * difference (exclude), xor, and intersect) on any type, number, and/or
- * combination of polygons. It is independent C# code that strictly serves
- * this purpose. More information can be found here:
- * 
- * http://www.angusj.com/delphi/clipper.php
- * http://sourceforge.net/projects/polyclipping/
- * 
- * - Andrew Davis
-*/
+//
+//
+// Author    :  Angus Johnson                                                   *
+// Version   :  4.8.4                                                           *
+// Date      :  1 June 2012                                                     *
+// Website   :  http://www.angusj.com                                           *
+// Copyright :  Angus Johnson 2010-2012                                         *
+//                                                                              *
+// License:                                                                     *
+// Use, modification & distribution is subject to Boost Software License Ver 1. *
+// http://www.boost.org/LICENSE_1_0.txt                                         *
+//                                                                              *
+// Attributions:                                                                *
+// The code in this library is an extension of Bala Vatti's clipping algorithm: *
+// "A generic solution to polygon clipping"                                     *
+// Communications of the ACM, Vol 35, Issue 7 (July 1992) pp 56-63.             *
+// http://portal.acm.org/citation.cfm?id=129906                                 *
+//                                                                              *
+// Computer graphics and geometric modeling: implementation and algorithms      *
+// By Max K. Agoston                                                            *
+// Springer; 1 edition (January 4, 2005)                                        *
+// http://books.google.com/books?q=vatti+clipping+agoston                       *
+//                                                                              *
+// See also:                                                                    *
+// "Polygon Offsetting by Computing Winding Numbers"                            *
+// Paper no. DETC2005-85513 pp. 565-575                                         *
+// ASME 2005 International Design Engineering Technical Conferences             *
+// and Computers and Information in Engineering Conference (IDETC/CIE2005)      *
+// September 24–28, 2005 , Long Beach, California, USA                          *
+// http://www.me.berkeley.edu/~mcmains/pubs/DAC05OffsetPolygon.pdf              *
+//                                                                              *
+//
+
+//
+// This is a translation of the Delphi Clipper library and the naming style
+// used has retained a Delphi flavour.
+//
+
+//
+// This Clipper Library code was imported into Pinta on June 6th, 2012 by
+// Andrew Davis of GSoC 2012 for the MagicWandTool selection modes
+// implementation. It calculates "boolean clipping operations" (union,
+// difference (exclude), xor, and intersect) on any type, number, and/or
+// combination of polygons. It is independent C# code that strictly serves
+// this purpose. More information can be found here:
+//
+// http://www.angusj.com/delphi/clipper.php
+// http://sourceforge.net/projects/polyclipping/
+//
+// - Andrew Davis
+//
 
 using System;
 using System.Collections.Generic;
-//using System.Text; //for Int128.AsString() & StringBuilder
 
 namespace ClipperLibrary
 {

Pinta.Core/Effects/BinaryPixelOp.cs

@@ -40,7 +40,7 @@ public unsafe virtual void Apply (ColorBgra* dst, ColorBgra* lhs, ColorBgra* rhs
 		/// </summary>
 		/// <param name="dst">The Surface to write pixels to.</param>
 		/// <param name="dstOffset">The pixel offset that defines the upper-left of the rectangle-of-interest for the dst Surface.</param>
-		/// <param name="lhs">The Surface to read pixels from for the lhs parameter given to the method <b>ColorBgra Apply(ColorBgra, ColorBgra)</b>b>.</param></param>
+		/// <param name="lhs">The Surface to read pixels from for the lhs parameter given to the method <b>ColorBgra Apply(ColorBgra, ColorBgra)</b>.</param>
 		/// <param name="lhsOffset">The pixel offset that defines the upper-left of the rectangle-of-interest for the lhs Surface.</param>
 		/// <param name="rhs">The Surface to read pixels from for the rhs parameter given to the method <b>ColorBgra Apply(ColorBgra, ColorBgra)</b></param>
 		/// <param name="rhsOffset">The pixel offset that defines the upper-left of the rectangle-of-interest for the rhs Surface.</param>

Pinta.Core/Effects/ColorBgra.cs

@@ -189,20 +189,6 @@ public override int GetHashCode()
             }
         }
 
-        /// <summary>
-        /// Gets the equivalent GDI+ PixelFormat.
-        /// </summary>
-        /// <remarks>
-        /// This property always returns PixelFormat.Format32bppArgb.
-        /// </remarks>
-//        public static PixelFormat PixelFormat
-//        {
-//            get
-//            {
-//                return PixelFormat.Format32bppArgb;
-//            }
-//        }
-
         /// <summary>
         /// Returns a new ColorBgra with the same color values but with a new alpha component value.
         /// </summary>
@@ -327,21 +313,6 @@ public static byte ClampToByte(int x)
                 return (byte)x;
             }
         }
-        /// <summary>
-        /// Constructs a new ColorBgra instance from the values in the given Color instance.
-        /// </summary>
-//        public static ColorBgra FromColor(Color c)
-//        {
-//            return FromBgra(c.B, c.G, c.R, c.A);
-//        }
-
-        /// <summary>
-        /// Converts this ColorBgra instance to a Color instance.
-        /// </summary>
-//        public Color ToColor()
-//        {
-//            return Color.FromArgb(A, R, G, B);
-//        }
 
         /// <summary>
         /// Smoothly blends between two colors.
@@ -615,9 +586,6 @@ public static ColorBgra BlendColorsWFP(ColorBgra[] c, double[] w)
 		/// <summary>
         /// Smoothly blends the given colors together, assuming equal weighting for each one.
         /// </summary>
-        /// <param name="colors"></param>
-        /// <param name="colorCount"></param>
-        /// <returns></returns>
         public unsafe static ColorBgra Blend(ColorBgra* colors, int count)
         {
             if (count < 0)

Pinta.Core/Effects/ISurfaceDraw.cs

@@ -32,19 +32,20 @@ public interface ISurfaceDraw
         /// <summary>
         /// Draws the object on to the given Surface starting at the given (x,y) offset.
         /// </summary>
-        /// <param name="g">The Surface to draw to.</param>
-        /// <param name="transformX">The value to be added to every X coordinate that is used for drawing.</param>
-        /// <param name="transformY">The value to be added to every Y coordinate that is used for drawing.</param>
+        /// <param name="dst">The Surface to draw to.</param>
+        /// <param name="tX">The value to be added to every X coordinate that is used for drawing.</param>
+        /// <param name="tY">The value to be added to every Y coordinate that is used for drawing.</param>
         void Draw(ImageSurface dst, int tX, int tY);
 
 
         /// <summary>
         /// Draws the object on to the given Surface starting at the given (x,y) offset after
         /// passing each pixel through the given pixel operation as in: dst = pixelOp(dst, src)
         /// </summary>
-        /// <param name="g">The Surface to draw to.</param>
-        /// <param name="transformX">The value to be added to every X coordinate that is used for drawing.</param>
-        /// <param name="transformY">The value to be added to every Y coordinate that is used for drawing.</param>
-        void Draw(ImageSurface dst, int tX, int tY, PixelOp pixelOp);
+        /// <param name="dst">The Surface to draw to.</param>
+        /// <param name="tX">The value to be added to every X coordinate that is used for drawing.</param>
+        /// <param name="tY">The value to be added to every Y coordinate that is used for drawing.</param>
+		/// <param name="pixelOp">The pixelOp to use for rendering.</param>
+		void Draw(ImageSurface dst, int tX, int tY, PixelOp pixelOp);
     }
 }

Pinta.Core/Effects/PixelOp.cs

@@ -45,7 +45,7 @@ public void Apply (ImageSurface dst, Gdk.Point dstOffset, ImageSurface src, Gdk.
 		/// </summary>
 		/// <param name="dst">The Surface to write pixels to, and from which pixels are read and used as the lhs parameter for calling the method <b>ColorBgra Apply(ColorBgra, ColorBgra)</b>.</param>
 		/// <param name="dstOffset">The pixel offset that defines the upper-left of the rectangle-of-interest for the dst Surface.</param>
-		/// <param name="src">The Surface to read pixels from for the rhs parameter given to the method <b>ColorBgra Apply(ColorBgra, ColorBgra)</b>b>.</param></param>
+		/// <param name="src">The Surface to read pixels from for the rhs parameter given to the method <b>ColorBgra Apply(ColorBgra, ColorBgra)</b>.</param>
 		/// <param name="srcOffset">The pixel offset that defines the upper-left of the rectangle-of-interest for the src Surface.</param>
 		/// <param name="roiSize">The size of the rectangles-of-interest for all Surfaces.</param>
 		public void ApplyBase (ImageSurface dst, Gdk.Point dstOffset, ImageSurface src, Gdk.Point srcOffset, Gdk.Size roiSize)

Pinta.Core/Effects/Utility.cs

@@ -173,8 +173,10 @@ public static ColorBgra Blend(ColorBgra ca, ColorBgra cb, byte cbAlpha)
 		/// Allows you to find the bounding box for a "region" that is described as an
 		/// array of bounding boxes.
 		/// </summary>
-		/// <param name="rectsF">The "region" you want to find a bounding box for.</param>
-		/// <returns>A RectangleF structure that surrounds the Region.</returns>
+		/// <param name="rects">The "region" you want to find a bounding box for.</param>
+		/// <param name="startIndex">Index of the first rectangle in the array to examine.</param>
+		/// <param name="length">Number of rectangles to examine, beginning at <b>startIndex</b>.</param>
+		/// <returns>A rectangle that surrounds the region.</returns>
 		public static Gdk.Rectangle GetRegionBounds (Gdk.Rectangle[] rects, int startIndex, int length)
 		{
 			if (rects.Length == 0) {

Pinta.Core/Extensions/CairoExtensions.cs

@@ -484,7 +484,7 @@ public static Rectangle DrawLine (this Context g, PointD p1, PointD p2, Color co
 		/// using the current stroke parameters.
 		/// 
 		/// The rectangle returned by Cairo.Context.StrokeExtents()
-		/// incorrectly specifies the X & Y coordinates of the
+		/// incorrectly specifies the X and Y coordinates of the
 		/// bottom-right corner of the Rectangle in the width and
 		/// height members. This method corrects the rectangle to
 		/// contain the width and height in the width and height members.
@@ -936,8 +936,9 @@ public static double GetRight (this Rectangle rect)
 		/// edges moved out from the center by dy.  Edges are moved
 		/// inwards when dx or dy are negative.
 		/// </summary>
-		/// <param name="dx">Dist to move sides from center.</param>
-		/// <param name="dy">Dist to move top & botom from center.</param>
+		/// <param name="rect">The source rectangle.</param>
+		/// <param name="dx">Distance to move sides from center.</param>
+		/// <param name="dy">Distance to move top and bottom from center.</param>
 		/// <returns>The inflated (or deflated) rectangle.</returns>
 		public static Rectangle Inflate (this Rectangle rect, int dx, int dy)
 		{
@@ -947,6 +948,7 @@ public static Rectangle Inflate (this Rectangle rect, int dx, int dy)
 		/// <summary>
 		/// Determines if the requested pixel coordinate is within bounds.
 		/// </summary>
+		/// <param name="surf">The image surface to check against.</param>
 		/// <param name="x">The x coordinate.</param>
 		/// <param name="y">The y coordinate.</param>
 		/// <returns>true if (x,y) is in bounds, false if it's not.</returns>

Pinta.Core/Extensions/GtkExtensions.cs

@@ -152,7 +152,6 @@ public static void AddImagePreview (this FileChooserDialog dialog)
 		/// <summary>
 		/// Update the image preview widget of a FileChooserDialog
 		/// </summary>
-		/// <param name="sender"></param>
 		private static void OnUpdateImagePreview (object sender, EventArgs e)
 		{
 			FileChooserDialog dialog = (FileChooserDialog)sender;

Pinta.Core/HistoryItems/TextHistoryItem.cs

@@ -49,8 +49,11 @@ public class TextHistoryItem : BaseHistoryItem
 		/// <param name="text">The history item's title.</param>
 		/// <param name="passedTextSurface">The stored TextLayer surface.</param>
 		/// <param name="passedUserSurface">The stored UserLayer surface.</param>
+		/// <param name="passedTextEngine">The text engine being used.</param>
 		/// <param name="passedUserLayer">The UserLayer being modified.</param>
-		public TextHistoryItem(string icon, string text, ImageSurface passedTextSurface, ImageSurface passedUserSurface, TextEngine passedTextEngine, UserLayer passedUserLayer) : base(icon, text)
+		public TextHistoryItem(string icon, string text, ImageSurface passedTextSurface,
+		                       ImageSurface passedUserSurface, TextEngine passedTextEngine,
+		                       UserLayer passedUserLayer) : base(icon, text)
 		{
 			userLayer = passedUserLayer;
 

Pinta.Core/ImageFormats/IImageImporter.cs

@@ -35,10 +35,8 @@ public interface IImageImporter
 		/// <summary>
 		/// Imports a document into Pinta.
 		/// </summary>
-		/// <param name='fileName'>
-		/// The name of the file to be imported.
-		/// </param>
-		void Import (string fileName);
+		/// <param name='filename'>The name of the file to be imported.</param>
+		void Import (string filename);
 
 		/// <summary>
 		/// Returns a thumbnail of an image.
@@ -48,15 +46,10 @@ public interface IImageImporter
 		/// returned pixbuf will need to be rescaled by the calling code if it
 		/// exceeds the maximum size.
 		/// </summary>
-		/// <returns>
-		/// The thumbnail, or null if the image could not be loaded.
-		/// </returns>			
-		/// <param name='maxWidth'>
-		/// The maximum width of the thumbnail.
-		/// </param>
-		/// <param name='maxHeight'>
-		/// The maximum height of the thumbnail.
-		/// </param>
+		/// <param name='filename'>The name of the file to be imported.</param>
+		/// <param name='maxWidth'>The maximum width of the thumbnail.</param>
+		/// <param name='maxHeight'>The maximum height of the thumbnail.</param>
+		/// <returns>The thumbnail, or null if the image could not be loaded.</returns>
 		Gdk.Pixbuf LoadThumbnail (string filename, int maxWidth, int maxHeight);
 	}
 }

Pinta.Core/Managers/EffectsManager.cs

@@ -108,7 +108,7 @@ public Gtk.Action RegisterEffect (BaseEffect effect)
 		/// <summary>
 		/// Unregister an effect with Pinta, causing it to be removed from the Effects menu.
 		/// </summary>
-		/// <param name="effect">The type of the effect to unregister</param>
+		/// <param name="effect_type">The type of the effect to unregister</param>
 		public void UnregisterInstanceOfEffect (System.Type effect_type)
 		{
 			foreach (BaseEffect effect in effects.Keys) {

Pinta.Core/Pinta.Core.csproj

@@ -41,6 +41,8 @@
     <ConsolePause>False</ConsolePause>
     <AllowUnsafeBlocks>True</AllowUnsafeBlocks>
     <CodeAnalysisRuleSet>AllRules.ruleset</CodeAnalysisRuleSet>
+    <GenerateDocumentation>true</GenerateDocumentation>
+    <NoWarn>1591</NoWarn>
   </PropertyGroup>
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
     <DebugType>none</DebugType>