Update docs

2020-07-02 18:39:13 +02:00
parent cb5951794d
commit cd80913346
3 changed files with 58 additions and 8 deletions
--- a/doc/op.html
+++ b/doc/op.html
@@ -97,6 +97,7 @@ function main() {
    </select>
  </div>
  <ul class="simple simple-toc" id="toc-list">
+<li><a class="reference" id="basic-usage_toc" href="#basic-usage">Basic Usage</a></li>
 <li>
  <a class="reference reference-toplevel" href="#7" id="57">Types</a>
  <ul class="simple simple-toc-section">
@@ -132,9 +133,22 @@ function main() {
  <div class="nine columns" id="content">
  <div id="tocRoot"></div>
  
-  <p class="module-desc"><p>This module contains a generic type that can be used as a return type for operations that could fail. It adds additional messages to the result.</p>
-<p>OP stands for &quot;Operation result&quot;.</p>
-</p>
+  <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Version:</th><td> 1.0.0</td></tr>
+<tr><th class="docinfo-name">Author:</th><td> luxick &lt;op@luxick.de&gt;</td></tr>
+</tbody></table><p>OP stands for &quot;Operation Result&quot;.</p>
+<p>This module contains a generic type that can be used as a return type for operations that could fail. It adds additional messages to the result.</p>
+<p>This module improves upon the <a class="reference external" href="https://nim-lang.org/docs/options.html">options module</a> in that additional messages can be passed along with the presence or absence of a value.</p>
+
+<h1><a class="toc-backref" id="basic-usage" href="#basic-usage">Basic Usage</a></h1><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">divide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">OP</span><span class="Punctuation">[</span><span class="Identifier">float</span><span class="Punctuation">]</span> <span class="Operator">=</span>
+  <span class="Comment">## This could fail</span>
+  <span class="Keyword">if</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
+    <span class="Keyword">return</span> <span class="Identifier">fail</span><span class="Punctuation">(</span><span class="Identifier">float</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Cannot divide by zero!&quot;</span><span class="Punctuation">)</span>
+  <span class="Keyword">else</span><span class="Punctuation">:</span>
+    <span class="Keyword">return</span> <span class="Identifier">ok</span> <span class="Identifier">a</span> <span class="Operator">/</span> <span class="Identifier">b</span>   <span class="Comment"># Wrap the result</span>
+
+<span class="Keyword">let</span> <span class="Identifier">r</span> <span class="Operator">=</span> <span class="Identifier">divide</span><span class="Punctuation">(</span><span class="DecNumber">42</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">)</span>
+<span class="Identifier">assert</span> <span class="Identifier">r</span><span class="Operator">.</span><span class="Identifier">isOk</span> <span class="Operator">==</span> <span class="Identifier">false</span>
+<span class="Identifier">assert</span> <span class="Identifier">r</span><span class="Operator">.</span><span class="Identifier">error</span> <span class="Operator">==</span> <span class="StringLit">&quot;Cannot divide by zero!&quot;</span></pre></p>
  <div class="section" id="7">
 <h1><a class="toc-backref" href="#7">Types</a></h1>
 <dl class="item">
@@ -202,7 +216,7 @@ Will create a new operation result with the given error message. The type for th
 <dt><pre><span class="Keyword">proc</span> <a href="#fail%2Ctypedesc%2Cstring"><span class="Identifier">fail</span></a><span class="Other">(</span><span class="Identifier">T</span><span class="Other">:</span> <span class="Identifier">typedesc</span><span class="Other">;</span> <span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span></pre></dt>
 <dd>

-Alias for <a class="reference external" href="#fail,string">fail[T](string) proc</a>
+Alias for <a class="reference external" href="#fail,string">fail[T](string)</a>

 </dd>

@@ -215,7 +229,7 @@ Alias for <a class="reference external" href="#fail,string">fail[T](string) proc
      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br/>
-        <small style="color: var(--hint);">Made with Nim. Generated: 2020-07-02 16:10:27 UTC</small>
+        <small style="color: var(--hint);">Made with Nim. Generated: 2020-07-02 16:37:38 UTC</small>
      </div>
    </div>
  </div>
--- a/src/op.nim
+++ b/src/op.nim
@@ -1,7 +1,29 @@
+## :Version: 1.0.0
+## :Author: luxick <op@luxick.de>
+##
+## OP stands for "Operation Result".
+##
 ## This module contains a generic type that can be used as a return type
 ## for operations that could fail. It adds additional messages to the result.
 ##
-## OP stands for "Operation result".
+##
+## This module improves upon the `options module<https://nim-lang.org/docs/options.html>`_
+## in that additional messages can be passed along with the presence or absence of a value.
+##
+## Basic Usage
+## -----------
+## .. code-block:: nim
+##
+##  proc divide(a, b: int): OP[float] =
+##    ## This could fail
+##    if b == 0:
+##      return fail(float, "Cannot divide by zero!")
+##    else:
+##      return ok a / b   # Wrap the result
+##
+##  let r = divide(42, 0)
+##  assert r.isOk == false
+##  assert r.error == "Cannot divide by zero!"

 type
  OP*[T] = object of RootObj
@@ -46,6 +68,6 @@ proc fail*[T](msg: string): OP[T] =
  OP[T](isOK: false, error: msg)

 proc fail*(T: typedesc, msg: string): OP[T] =
-  ## Alias for `fail[T](string) proc <#fail,string>`_
+  ## Alias for `fail[T](string)<#fail,string>`_
  fail[T] msg

--- a/tests/tests.nim
+++ b/tests/tests.nim
@@ -52,3 +52,17 @@ test "Check changing result":
  let data = checker()
  check data.isOk == false
  check data.error == "data got corrupted"
+
+test "Check divider proc":
+  proc divide(a, b: int): OP[float] =
+    if b == 0:
+      return fail(float, "Cannot divide by zero!")
+    else:
+      return ok a / b
+
+  let
+    a = 42
+    b = 0
+  let r = divide(a, b)
+  check r.isOk == false
+  check r.error == "Cannot divide by zero!"