chore(docs): rewrite documentation

Client-Example/Properties/AssemblyInfo.cs

@@ -27,10 +27,10 @@
 [assembly: AssemblyCulture("")]
 
 // The assembly version has the format "{Major}.{Minor}.{Build}.{Revision}".
-// The form "{Major}.{Minor}.*" will automatically update the build and revision,
-// and "{Major}.{Minor}.{Build}.*" will update just the revision.
+// The form "{Major}.{Minor}./// " will automatically update the build and revision,
+// and "{Major}.{Minor}.{Build}./// " will update just the revision.
 
-[assembly: AssemblyVersion("1.0.*")]
+[assembly: AssemblyVersion("1.0./// ")]
 
 // The following attributes are used to specify the signing key for the assembly, 
 // if desired. See the Mono documentation for more information about signing.

Client-test/CancelWorkflowInstanceTest.cs

@@ -1,6 +1,6 @@
-using System.Threading.Tasks;
 using GatewayProtocol;
 using NUnit.Framework;
+using System.Threading.Tasks;
 
 namespace Zeebe.Client
 {

Client-test/GatewayTestService.cs

@@ -28,11 +28,11 @@ public class GatewayTestService : Gateway.GatewayBase
 
         private readonly List<IMessage> requests = new List<IMessage>();
 
-        /**
-         * Contains the request handler, which return the specific response, for each specific type of request.
-         *
-         * Per default the response for a specific type are an empty response.
-         */
+        /// <summary>
+        /// Contains the request handler, which return the specific response, for each specific type of request.
+        /// 
+        /// Per default the response for a specific type are an empty response.
+        /// </summary>
         private readonly Dictionary<Type, RequestHandler> typedRequestHandler = new Dictionary<Type, RequestHandler>();
 
         public IList<IMessage> Requests => requests;
@@ -96,37 +96,37 @@ public override Task<UpdateJobRetriesResponse> UpdateJobRetries(UpdateJobRetries
 
         public override Task<DeployWorkflowResponse> DeployWorkflow(DeployWorkflowRequest request, ServerCallContext context)
         {
-            return Task.FromResult((DeployWorkflowResponse) HandleRequest(request, context));
+            return Task.FromResult((DeployWorkflowResponse)HandleRequest(request, context));
         }
 
         public override Task<CreateWorkflowInstanceResponse> CreateWorkflowInstance(CreateWorkflowInstanceRequest request, ServerCallContext context)
         {
-            return Task.FromResult((CreateWorkflowInstanceResponse) HandleRequest(request, context));
+            return Task.FromResult((CreateWorkflowInstanceResponse)HandleRequest(request, context));
         }
 
         public override Task<CancelWorkflowInstanceResponse> CancelWorkflowInstance(CancelWorkflowInstanceRequest request, ServerCallContext context)
         {
-            return Task.FromResult((CancelWorkflowInstanceResponse) HandleRequest(request, context));
+            return Task.FromResult((CancelWorkflowInstanceResponse)HandleRequest(request, context));
         }
 
         public override Task<UpdateWorkflowInstancePayloadResponse> UpdateWorkflowInstancePayload(UpdateWorkflowInstancePayloadRequest request, ServerCallContext context)
         {
-            return Task.FromResult((UpdateWorkflowInstancePayloadResponse) HandleRequest(request, context));
+            return Task.FromResult((UpdateWorkflowInstancePayloadResponse)HandleRequest(request, context));
         }
 
         public override Task<ResolveIncidentResponse> ResolveIncident(ResolveIncidentRequest request, ServerCallContext context)
         {
-            return Task.FromResult((ResolveIncidentResponse) HandleRequest(request, context));
+            return Task.FromResult((ResolveIncidentResponse)HandleRequest(request, context));
         }
 
         public override Task<ListWorkflowsResponse> ListWorkflows(ListWorkflowsRequest request, ServerCallContext context)
         {
-            return Task.FromResult((ListWorkflowsResponse) HandleRequest(request, context));
+            return Task.FromResult((ListWorkflowsResponse)HandleRequest(request, context));
         }
 
         public override Task<GetWorkflowResponse> GetWorkflow(GetWorkflowRequest request, ServerCallContext context)
         {
-            return Task.FromResult((GetWorkflowResponse) HandleRequest(request, context));
+            return Task.FromResult((GetWorkflowResponse)HandleRequest(request, context));
         }
 
         private IMessage HandleRequest(IMessage request, ServerCallContext context)

Client/Api/Clients/IJobClient.cs

@@ -16,53 +16,54 @@
 
 namespace Zeebe.Client.Api.Clients
 {
-    /**
-     * A client with access to all job-related operation:
-     * <li>complete a job
-     * <li>mark a job as failed
-     * <li>update the retries of a job
-     */
+    /// <summary>
+    /// A client with access to all job-related operation:
+    /// <li>complete a job
+    /// <li> mark a job as failed
+    /// <li> update the retries of a job
+    /// </summary>
     public interface IJobClient
     {
 
-        /**
-         * Command to complete a job.
-         *
-         * <pre>
-         * long jobKey = ..;
-         *
-         * jobClient
-         *  .NewCompleteJobCommand(jobKey)
-         *  .Payload(json)
-         *  .Send();
-         * </pre>
-         *
-         * <p>If the job is linked to a workflow instance then this command will complete the related
-         * activity and continue the flow.
-         *
-         * @param jobKey the key which identifies the job
-         * @return a builder for the command
-         */
+        /// <summary>
+        /// Command to complete a job.
+        /// 
+        /// <pre>
+        /// long jobKey = ..;
+        /// 
+        /// jobClient
+        ///  .NewCompleteJobCommand(jobKey)
+        ///  .Payload(json)
+        ///  .Send();
+        /// </pre>
+        /// 
+        /// <p>If the job is linked to a workflow instance then this command will complete the related
+        /// activity and continue the flow.
+        /// </p>
+        /// 
+        /// <param name="jobKey>the key which identifies the job</param>
+        /// <returns>a builder for the command
+
         ICompleteJobCommandStep1 NewCompleteJobCommand(long jobKey);
 
-        /**
-         * Command to mark a job as failed.
-         *
-         * <pre>
-         * long jobKey = ..;
-         *
-         * jobClient
-         *  .NewFailCommand(jobKey)
-         *  .Retries(3)
-         *  .Send();
-         * </pre>
-         *
-         * <p>If the given retries are greater than zero then this job will be picked up again by a job
-         * worker. Otherwise, an incident is created for this job.
-         *
-         * @param jobKey the key which identifies the job
-         * @return a builder for the command
-         */
+        /// <summary>
+        /// Command to mark a job as failed.
+        /// 
+        /// <pre>
+        /// long jobKey = ..;
+        /// 
+        /// jobClient
+        ///  .NewFailCommand(jobKey)
+        ///  .Retries(3)
+        ///  .Send();
+        /// </pre>
+        /// 
+        /// <p>If the given retries are greater than zero then this job will be picked up again by a job
+        /// worker. Otherwise, an incident is created for this job.
+        /// </p>
+        /// <param name="jobKey">the key which identifies the job</param>
+        /// <returns>a builder for the command
+        /// </summary>
         IFailJobCommandStep1 NewFailCommand(long jobKey);
     }
 }

Client/Api/Commands/ICompleteJobCommandStep1.cs

@@ -12,20 +12,18 @@
 //    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 //    See the License for the specific language governing permissions and
 //    limitations under the License.
-using System;
 using Zeebe.Client.Api.Responses;
 
 namespace Zeebe.Client.Api.Commands
 {
     public interface ICompleteJobCommandStep1 : IFinalCommandStep<ICompleteJobResponse>
     {
-        /**
-        * Set the payload to complete the job with.
-        *
-        * @param payload the payload (JSON) as String
-        * @return the builder for this command. Call {@link #send()} to complete the command and send it
-        *     to the broker.
-        */
+        /// <summary>
+        /// Set the payload to complete the job with.
+        /// </summary>
+        /// <param name="payload">the payload (JSON) as String</param>
+        /// <returns>the builder for this command. Call {@link #send()} to complete the command and send it
+        ///     to the broker.</returns>
         ICompleteJobCommandStep1 Payload(string payload);
     }
 }

Client/Api/Commands/ICreateWorkflowInstanceCommandStep1.cs

@@ -1,66 +1,58 @@
-using System;
-using System.Collections;
-using System.Collections.Generic;
-using System.IO;
-using Zeebe.Client.Api.Commands;
+using Zeebe.Client.Api.Commands;
 using Zeebe.Client.Api.Responses;
 
 namespace Zeebe.Client.Api.CommandsClient
 {
     public interface ICreateWorkflowInstanceCommandStep1
     {
-        /**
-         * Set the BPMN process id of the workflow to create an instance of. This is the static id of the
-         * process in the BPMN XML (i.e. "<bpmn:process id='my-workflow'>").
-         *
-         * @param bpmnProcessId the BPMN process id of the workflow
-         * @return the builder for this command
-         */
+        /// <summary>
+        /// Set the BPMN process id of the workflow to create an instance of. This is the static id of the
+        /// process in the BPMN XML (i.e. "&#60;bpmn:process id='my-workflow'&#62;").
+        /// </summary>
+        /// <param name="bpmnProcessId">the BPMN process id of the workflow</param>
+        /// <returns>the builder for this command</returns>
         ICreateWorkflowInstanceCommandStep2 BpmnProcessId(string bpmnProcessId);
 
-        /**
-         * Set the key of the workflow to create an instance of. The key is assigned by the broker while
-         * deploying the workflow. It can be picked from the deployment or workflow event.
-         *
-         * @param workflowKey the key of the workflow
-         * @return the builder for this command
-         */
+        /// <summary>
+        /// Set the key of the workflow to create an instance of. The key is assigned by the broker while
+        /// deploying the workflow. It can be picked from the deployment or workflow event.
+        /// </summary>
+        /// <param name="workflowKey">the key of the workflow</param>
+        /// <returns>the builder for this command</returns>
         ICreateWorkflowInstanceCommandStep3 WorkflowKey(long workflowKey);
     }
 
 
     public interface ICreateWorkflowInstanceCommandStep2
     {
-        /**
-         * Set the version of the workflow to create an instance of. The version is assigned by the
-         * broker while deploying the workflow. It can be picked from the deployment or workflow event.
-         *
-         * @param version the version of the workflow
-         * @return the builder for this command
-         */
+        /// <summary>
+        /// Set the version of the workflow to create an instance of. The version is assigned by the
+        /// broker while deploying the workflow. It can be picked from the deployment or workflow event.
+        /// </summary>
+        /// <param name="version">the version of the workflow</param>
+        /// <returns>the builder for this command</returns>
         ICreateWorkflowInstanceCommandStep3 Version(int version);
 
-        /**
-         * Use the latest version of the workflow to create an instance of.
-         *
-         * <p>If the latest version was deployed few moments before then it can happen that the new
-         * instance is created of the previous version.
-         *
-         * @return the builder for this command
-         */
+        /// <summary>
+        /// Use the latest version of the workflow to create an instance of.
+        /// <p>
+        /// If the latest version was deployed few moments before then it can happen that the new
+        /// instance is created of the previous version.
+        /// </p>
+        /// </summary>
+        /// <returns>the builder for this command</returns>
         ICreateWorkflowInstanceCommandStep3 LatestVersion();
     }
 
 
     public interface ICreateWorkflowInstanceCommandStep3 : IFinalCommandStep<IWorkflowInstanceResponse>
     {
-        /**
-         * Set the initial payload of the workflow instance.
-         *
-         * @param payload the payload (JSON) as String
-         * @return the builder for this command. Call {@link #send()} to complete the command and send
-         *     it to the broker.
-         */
+        /// <summary>
+        /// Set the initial payload of the workflow instance.
+        /// </summary>
+        /// <param name="payload">the payload (JSON) as String</param>
+        /// <returns>the builder for this command. Call {@link #send()} to complete the command and send
+        ///     it to the broker.</returns>
         ICreateWorkflowInstanceCommandStep3 Payload(string payload);
     }
 }