(GH-18) add wyam-documentation

README.md

@@ -26,6 +26,8 @@
 
 ## Usage
 
+See also the [local documentation][documentation] and [api][api]
+
 ### Adding files
 
 ```cs
@@ -93,3 +95,5 @@ Thanks goes to these wonderful people ([emoji key][emoji-key]):
 [license]: LICENSE.txt
 [standard-readme]: https://github.com/RichardLitt/standard-readme
 [standard-readme compliant]: https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square
+[documentation]: https://cake-contrib.github.io/Cake.7zip/
+[api]: https://cakebuild.net/api/Cake.7zip/

docs/input/index.cshtml

@@ -0,0 +1,34 @@
+---
+Title: Cake.7zip
+NoSidebar: true
+NoContainer: false
+NoGutter: true
+---
+
+<div class="container">				
+	<h1>What is it?</h1>
+    <p>
+        Cake.7zip is an Addin for <a href="http://cakebuild.net/">Cake</a> to use <a href="https://www.7-zip.org/">7Zip</a>.
+    </p>
+</div>
+<div class="container">
+	<h1>Usage</h1>
+  <div>
+  <h2>Usage in Cake</H2>
+    <p>
+        Have a look at <a href="api/Cake.SevenZip/SevenZipAliases/">SevenZipAliases</a> on how to integrate with <a href="http://cakebuild.net/">Cake</a>. There are also some examples there.
+    </p>
+  </div>
+  <div>
+  <h2>Available Commands</H2>
+    <p>
+        All available Commands are listed at the <a href="api/Cake.SevenZip/ICommand/">ICommand</a>-Interface.
+    </p>
+  </div>
+  <div>
+  <h2>Available Switches</H2>
+    <p>
+        All available Switches are listed at the <a href="api/Cake.SevenZip/ISupportSwitch/">ISupportSwitch</a>-Interface. However, not all commands support every switch.
+    </p>
+  </div>
+</div>

src/Cake.7zip.Tests/FluentBuilder/FluentBuilderFixture.cs

@@ -4,17 +4,17 @@ namespace Cake.SevenZip.Tests
 
     public class FluentBuilderFixture
     {
-        internal SevenZipBuilderContext Context { get; private set; }
+        internal CommandBuilder Context { get; private set; }
 
         public FluentBuilderFixture()
         {
-            Context = new SevenZipBuilderContext();
+            Context = new CommandBuilder();
         }
 
         public string EvaluateArgs()
         {
             var args = new ProcessArgumentBuilder();
-            Context.Settings.Command.BuildArguments(ref args);
+            Context.Command.BuildArguments(ref args);
             return args.Render();
         }
     }

src/Cake.7zip/Builder/AddCommandBuilder.cs

@@ -4,8 +4,8 @@ namespace Cake.SevenZip
 
     /// <summary>
     /// Builder for <see cref="AddCommand"/>.
-    /// </summary>
     /// <seealso cref="ISupportSwitchBuilder{T}" />
+    /// </summary>
     public sealed class AddCommandBuilder :
         ISupportSwitchBuilder<ISupportSwitchVolume>,
         ISupportSwitchBuilder<ISupportSwitchCompressionMethod>,

src/Cake.7zip/Builder/SevenZipBuilderContext.cs → src/Cake.7zip/Builder/CommandBuilder.cs

@@ -1,26 +1,18 @@
 namespace Cake.SevenZip
 {
     /// <summary>
-    /// Builder for Commands.
+    /// Builder for all <see cref="ICommand"/>s.
     /// Do NOT call WithCommand... multiple times.
     /// </summary>
-    public sealed class SevenZipBuilderContext
+    public sealed class CommandBuilder
     {
         /// <summary>
-        /// Initializes a new instance of the <see cref="SevenZipBuilderContext"/> class.
-        /// </summary>
-        internal SevenZipBuilderContext()
-        {
-            Settings = new SevenZipSettings();
-        }
-
-        /// <summary>
-        /// Gets the settings.
+        /// Gets or sets the Command.
         /// </summary>
         /// <value>
-        /// The settings.
+        /// The Command.
         /// </value>
-        internal SevenZipSettings Settings { get; }
+        internal ICommand Command { get; set; }
 
         /// <summary>
         /// Makes this Builder an AddCommand-Builder.
@@ -29,7 +21,7 @@ internal SevenZipBuilderContext()
         public AddCommandBuilder InAddMode()
         {
             var command = new AddCommand();
-            Settings.Command = command;
+            Command = command;
             return new AddCommandBuilder(ref command);
         }
 
@@ -40,7 +32,7 @@ public AddCommandBuilder InAddMode()
         public ExtractCommandBuilder InExtractMode()
         {
             var command = new ExtractCommand();
-            Settings.Command = command;
+            Command = command;
             return new ExtractCommandBuilder(ref command);
         }
     }

src/Cake.7zip/Builder/ExtractCommandBuilder.cs

@@ -4,8 +4,8 @@ namespace Cake.SevenZip
 
     /// <summary>
     /// Builder for <see cref="ExtractCommand"/>.
-    /// </summary>
     /// <seealso cref="ISupportSwitchBuilder{T}" />
+    /// </summary>
     public class ExtractCommandBuilder :
         ISupportSwitchBuilder<ISupportSwitchArchiveType>,
         ISupportSwitchBuilder<ISupportSwitchCompressionMethod>,

src/Cake.7zip/Builder/SwitchSswBuilder.cs → src/Cake.7zip/Builder/SwitchCompressFilesOpenForWritingBuilder.cs

@@ -1,10 +1,10 @@
-namespace Cake.SevenZip
+namespace Cake.SevenZip
 {
     /// <summary>
     /// Extensions for all Builders that support <see cref="ISupportSwitchCompressFilesOpenForWriting"/>.
     /// <seealso cref="ISupportSwitchBuilder{T}"/>
     /// </summary>
-    public static class SwitchSswBuilder
+    public static class SwitchCompressFilesOpenForWritingBuilder
     {
         /// <summary>
         /// fluent setter for <see cref="ISupportSwitchCompressFilesOpenForWriting"/>.

src/Cake.7zip/Builder/SwitchCompressionMethodsBuilder.cs → src/Cake.7zip/Builder/SwitchCompressionMethodBuilder.cs

@@ -1,12 +1,12 @@
-namespace Cake.SevenZip
+namespace Cake.SevenZip
 {
     using System;
 
     /// <summary>
     /// Extensions for all Builders that support <see cref="ISupportSwitchCompressionMethod"/>.
     /// <seealso cref="ISupportSwitchBuilder{T}"/>
     /// </summary>
-    public static class SwitchCompressionMethodsBuilder
+    public static class SwitchCompressionMethodBuilder
     {
         /// <summary>
         /// fluent setter for <see cref="ISupportSwitchCompressionMethod"/> using an action.

src/Cake.7zip/Builder/SwitchSniBuilder.cs → src/Cake.7zip/Builder/SwitchNtSecurityInformationBuilder.cs

@@ -4,7 +4,7 @@ namespace Cake.SevenZip
     /// Extensions for all Builders that support <see cref="ISupportSwitchNtSecurityInformation"/>.
     /// <seealso cref="ISupportSwitchBuilder{T}"/>
     /// </summary>
-    public static class SwitchSniBuilder
+    public static class SwitchNtSecurityInformationBuilder
     {
         /// <summary>
         /// fluent setter for <see cref="ISupportSwitchNtSecurityInformation"/>.

src/Cake.7zip/Builder/SwitchSnsBuilder.cs → src/Cake.7zip/Builder/SwitchNtfsAlternateStreamsBuilder.cs

@@ -4,7 +4,7 @@ namespace Cake.SevenZip
     /// Extensions for all Builders that support <see cref="ISupportSwitchNtfsAlternateStreams"/>.
     /// <seealso cref="ISupportSwitchBuilder{T}"/>
     /// </summary>
-    public static class SwitchSnsBuilder
+    public static class SwitchNtfsAlternateStreamsBuilder
     {
         /// <summary>
         /// fluent setter for <see cref="ISupportSwitchNtfsAlternateStreams"/>.

src/Cake.7zip/Builder/SwitchStlBuilder.cs → src/Cake.7zip/Builder/SwitchSetTimestampFromMostRecentFileBuilder.cs

@@ -4,7 +4,7 @@ namespace Cake.SevenZip
     /// Extensions for all Builders that support <see cref="ISupportSwitchTimestampFromMostRecentFile"/>.
     /// <seealso cref="ISupportSwitchBuilder{T}"/>
     /// </summary>
-    public static class SwitchStlBuilder
+    public static class SwitchSetTimestampFromMostRecentFileBuilder
     {
         /// <summary>
         /// fluent setter for <see cref="ISupportSwitchTimestampFromMostRecentFile"/>.

src/Cake.7zip/Commands/AddCommand.cs

@@ -7,7 +7,8 @@ namespace Cake.SevenZip
     using Cake.Core.IO;
 
     /// <summary>
-    /// Represents an Add-Command.
+    /// Adds files to archive.
+    /// (Command: a).
     /// </summary>
     public sealed class AddCommand : ICommand,
         ISupportSwitchVolume,

src/Cake.7zip/Commands/ExtractCommand.cs

@@ -6,7 +6,19 @@ namespace Cake.SevenZip
     using Cake.Core.IO;
 
     /// <summary>
-    /// Represents an Extract-Command.
+    /// Extract-Command - With or without full path
+    /// (Commands: e and x).
+    /// <para>
+    /// With UseFullPath set to false, this represents the e-command:
+    /// Extracts files from an archive to the current directory or to the output directory.
+    /// The output directory can be specified by -o (Set Output Directory) switch.
+    /// This command copies all extracted files to one directory.
+    /// </para>
+    /// <para>
+    /// With UseFullPath set to true, this represents the x-command:
+    /// Extracts files from an archive with their full paths in the current directory,
+    /// or in an output directory if specified.
+    /// </para>
     /// </summary>
     public sealed class ExtractCommand : ICommand,
         ISupportSwitchIncludeFilenames,

src/Cake.7zip/Commands/ICommand.cs

@@ -3,7 +3,7 @@ namespace Cake.SevenZip
     using Cake.Core.IO;
 
     /// <summary>
-    /// Base-Class for commands like <see cref="AddCommand"/>.
+    /// Interface for all commands. (E.g. <see cref="AddCommand"/>).
     /// </summary>
     public interface ICommand
     {
@@ -13,18 +13,5 @@ public interface ICommand
         /// </summary>
         /// <param name="builder">The builder.</param>
         void BuildArguments(ref ProcessArgumentBuilder builder);
-
-        /* Missing:
-    b  Benchmark
-    d  Delete
-    e  Extract
-    h  Hash
-    i  Show information about supported formats
-    l  List
-    rn Rename
-    t  Test
-    u  Update
-    x  eXtract with full paths
-         */
     }
 }

src/Cake.7zip/SevenZipAliases.cs

@@ -4,26 +4,36 @@ namespace Cake.SevenZip
 
     using Cake.Core;
     using Cake.Core.Annotations;
+    using Cake.Core.Tooling;
 
     /// <summary>
     /// <para>Functions to call <see href="https://7-zip.org/">7-Zip</see>.</para>
     /// <para>
-    /// In order to use this addin, make sure 7zip is installed on the system
-    /// and add the following to your build.cake.
-    /// <code><![CDATA[
+    /// In order to use this addin, 7za.exe has to be available.
+    /// The only tested option currently is unsing
+    /// <see href="https://www.nuget.org/packages/7-Zip.CommandLine/">7-Zip.CommandLine from nuget</see>
+    /// though other options may work.
+    /// Currently the following formats are supported: 7z, xz, lzma, cab, zip, gzip, bzip2 and tar.
+    /// (Those are the formats supported by the standalone 7za.exe.)
+    /// </para>
+    /// <para>
+    /// To install add the following lines to your cake-file:
+    /// <code>
+    /// <![CDATA[
     /// #tool "nuget:?package=7-Zip.CommandLine"
     /// #addin "nuget:?package=Cake.7zip"
-    /// ]]></code>
+    /// ]]>
+    /// </code>
     /// </para>
     /// </summary>
     [CakeAliasCategory("7Zip")]
     public static class SevenZipAliases
     {
         /// <summary>
-        /// Runs a fluent builder for 7zip.
+        /// Runs 7zip, using a fluent builder for configuration.
         /// </summary>
         /// <param name="context">The <see cref="ICakeContext"/>.</param>
-        /// <param name="action">The fluent <see cref="SevenZipBuilderContext"/>-Builder.</param>
+        /// <param name="action">The fluent <see cref="CommandBuilder"/>.</param>
         /// <example>
         /// <code>
         /// <![CDATA[
@@ -54,15 +64,39 @@ public static class SevenZipAliases
         /// </code>
         /// </example>
         [CakeMethodAlias]
-        public static void SevenZip(this ICakeContext context, Action<SevenZipBuilderContext> action)
+        public static void SevenZip(this ICakeContext context, Action<CommandBuilder> action)
+        {
+            SevenZip(context, new SevenZipSettings(), action);
+        }
+
+        /// <summary>
+        /// <para>
+        /// Runs 7zip, using <see cref="SevenZipSettings"/> for configuration and additionally
+        /// <see cref="CommandBuilder"/> for fluent configuration of the Command.
+        /// </para>
+        /// <para>
+        /// Works exactly like <see cref="SevenZipAliases.SevenZip(ICakeContext, Action{CommandBuilder})"/>
+        /// However, the settings are supplied to set e.g. the <c>ToolPath</c> or something else.
+        /// </para>
+        /// <para>
+        /// <strong>DO NOT</strong> set <c>Command</c> on the <see cref="SevenZipSettings"/>,
+        /// as it will be overwritten by the <see cref="CommandBuilder"/>.
+        /// </para>
+        /// </summary>
+        /// <param name="context">The <see cref="ICakeContext"/>.</param>
+        /// <param name="settings">The <see cref="SevenZipSettings"/>.</param>
+        /// <param name="action">The fluent <see cref="CommandBuilder"/>-Builder.</param>
+        [CakeMethodAlias]
+        public static void SevenZip(this ICakeContext context, SevenZipSettings settings, Action<CommandBuilder> action)
         {
-            var builder = new SevenZipBuilderContext();
+            var builder = new CommandBuilder();
             action(builder);
-            SevenZip(context, builder.Settings);
+            settings.Command = builder.Command;
+            SevenZip(context, settings);
         }
 
         /// <summary>
-        /// Runs a non-fluent 7zip.
+        /// Runs 7zip, using <see cref="SevenZipSettings"/> for configuration.
         /// </summary>
         /// <param name="context">The <see cref="ICakeContext"/>.</param>
         /// <param name="settings">The <see cref="SevenZipSettings"/>.</param>

src/Cake.7zip/Switches/BaseSwitchCollection.cs

@@ -5,10 +5,13 @@ namespace Cake.SevenZip
     using Cake.Core.IO;
 
     /// <summary>
-    /// Base for a collection of switches.
+    /// Base for for switches that can be given multiple times.
+    /// An example is <see cref="ISupportSwitchExcludeFilenames"/> (-x!*.pdf -x!*.xml) which uses
+    /// <see cref="SwitchExcludeFilenameCollection"/> (which implements this BaseCollection) to set
+    /// multiple <see cref="SwitchExcludeFilename"/>.
+    /// <seealso cref="ISwitch" />
     /// </summary>
     /// <typeparam name="T">The Switch-Type.</typeparam>
-    /// <seealso cref="ISwitch" />
     public abstract class BaseSwitchCollection<T> : ISwitch
       where T : ISwitch
     {

src/Cake.7zip/Switches/ISupportSwitch.cs

@@ -1,9 +1,10 @@
 namespace Cake.SevenZip
 {
-    using Cake.Core.IO;
-
     /// <summary>
-    /// Base for all Command-Support-Switches.
+    /// Interfaces for all switches.
+    /// Commands "support" swithches by implementing an ISupportSwitch
+    /// (e.g. <see cref="ISupportSwitchPassword"/> is implemented in all commands
+    /// that support setting a passeword (-p).
     /// </summary>
     public interface ISupportSwitch
     {