Document save, make params consistant

src/ImageSharp/ImageExtensions.cs

@@ -7,12 +7,11 @@ using System.IO;
 using System.Text;
 using SixLabors.ImageSharp.Advanced;
 using SixLabors.ImageSharp.Formats;
-using SixLabors.ImageSharp.PixelFormats;
 
 namespace SixLabors.ImageSharp
 {
     /// <summary>
-    /// Extension methods over Image{TPixel}.
+    /// Extension methods for the <see cref="Image"/> type.
     /// </summary>
     public static partial class ImageExtensions
     {
@@ -20,13 +19,13 @@ namespace SixLabors.ImageSharp
         /// Writes the image to the given stream using the currently loaded image format.
         /// </summary>
         /// <param name="source">The source image.</param>
-        /// <param name="filePath">The file path to save the image to.</param>
+        /// <param name="path">The file path to save the image to.</param>
-        /// <exception cref="System.ArgumentNullException">Thrown if the stream is null.</exception>
+        /// <exception cref="ArgumentNullException">The path is null.</exception>
-        public static void Save(this Image source, string filePath)
+        public static void Save(this Image source, string path)
         {
-            Guard.NotNullOrWhiteSpace(filePath, nameof(filePath));
+            Guard.NotNull(path, nameof(path));
 
-            string ext = Path.GetExtension(filePath);
+            string ext = Path.GetExtension(path);
             IImageFormat format = source.GetConfiguration().ImageFormatsManager.FindFormatByFileExtension(ext);
             if (format is null)
             {
@@ -34,7 +33,7 @@ namespace SixLabors.ImageSharp
                 sb.AppendLine($"No encoder was found for extension '{ext}'. Registered encoders include:");
                 foreach (IImageFormat fmt in source.GetConfiguration().ImageFormats)
                 {
-                    sb.AppendLine($" - {fmt.Name} : {string.Join(", ", fmt.FileExtensions)}");
+                    sb.AppendFormat(" - {0} : {1}{2}", fmt.Name, string.Join(", ", fmt.FileExtensions), Environment.NewLine);
                 }
 
                 throw new NotSupportedException(sb.ToString());
@@ -48,26 +47,28 @@ namespace SixLabors.ImageSharp
                 sb.AppendLine($"No encoder was found for extension '{ext}' using image format '{format.Name}'. Registered encoders include:");
                 foreach (KeyValuePair<IImageFormat, IImageEncoder> enc in source.GetConfiguration().ImageFormatsManager.ImageEncoders)
                 {
-                    sb.AppendLine($" - {enc.Key} : {enc.Value.GetType().Name}");
+                    sb.AppendFormat(" - {0} : {1}{2}", enc.Key, enc.Value.GetType().Name, Environment.NewLine);
                 }
 
                 throw new NotSupportedException(sb.ToString());
             }
 
-            source.Save(filePath, encoder);
+            source.Save(path, encoder);
         }
 
         /// <summary>
         /// Writes the image to the given stream using the currently loaded image format.
         /// </summary>
         /// <param name="source">The source image.</param>
-        /// <param name="filePath">The file path to save the image to.</param>
+        /// <param name="path">The file path to save the image to.</param>
         /// <param name="encoder">The encoder to save the image with.</param>
-        /// <exception cref="ArgumentNullException">Thrown if the encoder is null.</exception>
+        /// <exception cref="ArgumentNullException">The path is null.</exception>
-        public static void Save(this Image source, string filePath, IImageEncoder encoder)
+        /// <exception cref="ArgumentNullException">The encoder is null.</exception>
+        public static void Save(this Image source, string path, IImageEncoder encoder)
         {
+            Guard.NotNull(path, nameof(path));
             Guard.NotNull(encoder, nameof(encoder));
-            using (Stream fs = source.GetConfiguration().FileSystem.Create(filePath))
+            using (Stream fs = source.GetConfiguration().FileSystem.Create(path))
             {
                 source.Save(fs, encoder);
             }
@@ -79,10 +80,20 @@ namespace SixLabors.ImageSharp
         /// <param name="source">The source image.</param>
         /// <param name="stream">The stream to save the image to.</param>
         /// <param name="format">The format to save the image in.</param>
-        /// <exception cref="ArgumentNullException">Thrown if the stream is null.</exception>
+        /// <exception cref="ArgumentNullException">The stream is null.</exception>
+        /// <exception cref="ArgumentNullException">The format is null.</exception>
+        /// <exception cref="NotSupportedException">The stream is not writable.</exception>
+        /// <exception cref="NotSupportedException">No encoder available for provided format.</exception>
         public static void Save(this Image source, Stream stream, IImageFormat format)
         {
+            Guard.NotNull(stream, nameof(stream));
             Guard.NotNull(format, nameof(format));
+
+            if (!stream.CanWrite)
+            {
+                throw new NotSupportedException("Cannot write to the stream.");
+            }
+
             IImageEncoder encoder = source.GetConfiguration().ImageFormatsManager.FindEncoder(format);
 
             if (encoder is null)
@@ -92,7 +103,7 @@ namespace SixLabors.ImageSharp
 
                 foreach (KeyValuePair<IImageFormat, IImageEncoder> val in source.GetConfiguration().ImageFormatsManager.ImageEncoders)
                 {
-                    sb.AppendLine($" - {val.Key.Name} : {val.Value.GetType().Name}");
+                    sb.AppendFormat(" - {0} : {1}{2}", val.Key.Name, val.Value.GetType().Name, Environment.NewLine);
                 }
 
                 throw new NotSupportedException(sb.ToString());
@@ -113,9 +124,12 @@ namespace SixLabors.ImageSharp
         /// </summary>
         /// <param name="source">The source image</param>
         /// <param name="format">The format.</param>
+        /// <exception cref="ArgumentNullException">The format is null.</exception>
         /// <returns>The <see cref="string"/></returns>
         public static string ToBase64String(this Image source, IImageFormat format)
         {
+            Guard.NotNull(format, nameof(format));
+
             using var stream = new MemoryStream();
             source.Save(stream, format);