Skip to content

Commit

Permalink
lots of docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jaredly
jaredly committed May 19, 2018
1 parent 7312ecb commit bcee577
Show file tree
Hide file tree
Showing 11 changed files with 230 additions and 80 deletions.
1 change: 1 addition & 0 deletions bsconfig.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
],
"bs-dependencies": ["rex-json", "minimist.re", "pack.re"],
"ocaml-dependencies": ["compiler-libs", "unix", "bigarray", "str"],
"public": ["Main"],
"entries": [{
"backend": "native",
"main-module": "Main"
Expand Down
18 changes: 9 additions & 9 deletions docs/Interactive Code Snippets.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@
<a href="#interactive-code-snippets" id="interactive-code-snippets"><h1>Interactive Code Snippets</h1></a>

<p>If you put this in your doc-comments:</p>
<pre class='txt'><code class='txt'>```reason
<pre class='code-txt txt'><code class='txt'>```reason
print_endline(&quot;Hello&quot;);
```</code></pre>

Expand Down Expand Up @@ -227,7 +227,7 @@
<p>When you execute, will trap the console &amp; display below (should also send to real console).</p>
<a href="#displaying-errors" id="displaying-errors"><h3>Displaying errors</h3></a>

<pre class='txt'><code class='txt'>```re
<pre class='code-txt txt'><code class='txt'>```re
This is a syntax error
```</code></pre>

Expand All @@ -252,7 +252,7 @@
</div>

<p>If you <em>intend</em> to have a syntax error, add <code>parse-fail</code> to the header, like <code>re;parse-fail</code>. Other wise you&#39;ll get a big warning when you run docre.</p>
<pre class='txt'><code class='txt'>```re
<pre class='code-txt txt'><code class='txt'>```re
3 + &quot;type error&quot;
```</code></pre>

Expand Down Expand Up @@ -283,7 +283,7 @@

<a href="#--hiding-prefix--amp--suffix-lines" id="--hiding-prefix--amp--suffix-lines"><h4><code>#</code> Hiding prefix &amp; suffix lines</h4></a>

<pre class='txt'><code class='txt'>```
<pre class='code-txt txt'><code class='txt'>```
#let x = &quot;this line will be hidden&quot;;
#let y = &quot;this line will also be hidden&quot;;
let z = x ++ y; /* wow where did that come from */
Expand Down Expand Up @@ -385,14 +385,14 @@

<a href="#canvas-have-a-canvas" id="canvas-have-a-canvas"><h4><code>canvas</code> Have a canvas</h4></a>

<pre class='txt'><code class='txt'>```canvas
<pre class='code-txt txt'><code class='txt'>```canvas
Js.log(&quot;A shared canvas is created, and floats over to the right. The canvasId is available as &#39;sandboxId&#39;.&quot;);
[@bs.val] external sandboxId: string = &quot;&quot;;
```</code></pre>

<a href="#shared-name--share-something" id="shared-name--share-something"><h4><code>shared(name)</code> Share something</h4></a>

<pre class='txt'><code class='txt'>```shared(awesome)
<pre class='code-txt txt'><code class='txt'>```shared(awesome)
let something = &quot;A string I want to use later&quot;;
```</code></pre>

Expand Down Expand Up @@ -463,7 +463,7 @@
</div>

<p>And then use it later:</p>
<pre class='txt'><code class='txt'>```use(awesome)
<pre class='code-txt txt'><code class='txt'>```use(awesome)
Js.log(something);
```</code></pre>

Expand Down Expand Up @@ -543,15 +543,15 @@
</div>

<a href="#hide-hide-a-code-block" id="hide-hide-a-code-block"><h4><code>hide</code> Hide a code block</h4></a><p>Nice if you want a shared block that doesn&#39;t make sense on its own:</p>
<pre class='txt'><code class='txt'>```hide
<pre class='code-txt txt'><code class='txt'>```hide
let x = 10;
```</code></pre>



<a href="#write-the-source-in-ocaml" id="write-the-source-in-ocaml"><h4>Write the source in OCaml</h4></a>

<pre class='txt'><code class='txt'>```ml
<pre class='code-txt txt'><code class='txt'>```ml
Js.log &quot;this was written in ocaml&quot;;
```</code></pre>

Expand Down
139 changes: 85 additions & 54 deletions docs/Writing Documentation.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,10 @@
<a href="#writing-documentation" class='level-1 header'>Writing Documentation</a>
<a href="#top-level-module-documentation" class='level-2 header'>Top-level module documentation</a>
<a href="#per-value-documentation" class='level-2 header'>Per-value documentation</a>
<a href="#pragmas" class='level-2 header'>Pragmas</a>
<a href="#-doc-followed-by-a-comma-separated-list-of-names" class='level-3 header'><code>@doc</code> followed by a comma-separated list of names</a>
<a href="#-rest" class='level-3 header'><code>@rest</code></a>
<a href="#-all" class='level-3 header'><code>@all</code></a>
</div>
<div class='project-title'>Package modules</div><div class='project-listing'><a href="./api/Ast.html">Ast</a>
<a href="./api/Comment.html">Comment</a>
Expand Down Expand Up @@ -151,72 +155,99 @@

<a href="#top-level-module-documentation" id="top-level-module-documentation"><h2>Top-level module documentation</h2></a>

<p>The first &quot;standalone&quot; comment in a module is treated as the main documentation block for that module.</p>
<p>The first &quot;standalone&quot; comment in a module is treated as the main documentation block for that module. Note the trailing semicolon, and that it starts with exactly two asterisks.</p>
<p>Your top-level documentation should guide the user through the exposed types &amp; values in your module, in order of importance. If the module exports a &quot;main&quot; function, that should be listed at the top, with lesser-used items listed later. It can be helpful to split the documentation into sections via markdown headers, especially if there are many items exported from a module.</p>
<blockquote><p>🙏 Please include at least one example in the top-level documentation of each module. See &quot;Interactive code snippets&quot; for details.</p>
</blockquote>

<div class='code-block' data-block-syntax="re">

<pre class='code' data-block-id='8' id='block-8'><code>/**
* This is a standalone block
<pre class='code' data-block-id='9' id='block-9'><code>/**
* # FlorpBloop
*
* This module is for turning florps into bloops.
*
* Here&#39;s how to use it:
* ```re
* open FlorpBloop;
* let bloop = florpToBloop(Florp.create());
* let florp = bloopToFlorp(bloop);
* assert(isValidFlorp(florp));
* ```
*
* ## General data transformation functions
*
* @doc florpToBloop, bloopToFlorp, convertManyFlorpsToBloops
*
* ## Less-used, but also helpful utilities
*
* @doc isValidFlorp, canConvertToBloop
*
* Note the trailing semicolon, and the two asterisks at the start (must be exactly two).
*/;</code></pre>

<script type='docre-source' data-block-id="8">/**
* This is a standalone block
*
* Note the trailing semicolon, and the two asterisks at the start (must be exactly two).
*/;</script>
<div data-block-id='8' data-context="normal" data-block-syntax="re" class='block-target'></div><script type='docre-bundle' data-block-id='8'>
;(function() { // generated by pack.re
let modules = {}
let initializers = {
1: function(module, exports, require) {// Generated by BUCKLESCRIPT VERSION 2.1.1, PLEASE EDIT WITH CARE
/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */
//# sourceURL=./node_modules/.docre/Docre__Writing_Documentation_md_CODE_BLOCK_8.re_ppx.js
}
};
let nameMap = {
"./node_modules/.docre/Docre__Writing_Documentation_md_CODE_BLOCK_8.re_ppx.js": 1
}
let require = (id) => {
if (!modules[id]) {
modules[id] = {exports: {}}
initializers[id](modules[id], modules[id].exports, require)
}
return modules[id].exports
};
require(1)})();</script>


</div><div class='code-block' data-block-syntax="ml">

<pre class='code' data-block-id='8-alt' id='block-8-alt'><code>[@@@ocaml.ppx.context { cookies = [] }]
<pre class='code' data-block-id='9-alt' id='block-9-alt'><code>[@@@ocaml.ppx.context { cookies = [] }]
[@@@ocaml.doc
&quot;\n * This is a standalone block\n *\n * Note the trailing semicolon, and the two asterisks at the start (must be exactly two).\n &quot;]</code></pre>
&quot;\n * # FlorpBloop\n *\n * This module is for turning florps into bloops.\n *\n * Here&#39;s how to use it:\n * ```re\n * open FlorpBloop;\n * let bloop = florpToBloop(Florp.create());\n * let florp = bloopToFlorp(bloop);\n * assert(isValidFlorp(florp));\n * ```\n *\n * ## General data transformation functions\n *\n * @doc florpToBloop, bloopToFlorp, convertManyFlorpsToBloops\n *\n * ## Less-used, but also helpful utilities\n *\n * @doc isValidFlorp, canConvertToBloop\n *\n &quot;]</code></pre>



<script type='docre-source' data-block-id="8-alt">[@@@ocaml.ppx.context { cookies = [] }]
[@@@ocaml.doc
"\n * This is a standalone block\n *\n * Note the trailing semicolon, and the two asterisks at the start (must be exactly two).\n "]</script>
<div data-block-id='8-alt' data-context="normal" data-block-syntax="ml" class='block-target'></div><script type='docre-bundle' data-block-id='8-alt'>
;(function() { // generated by pack.re
let modules = {}
let initializers = {
1: function(module, exports, require) {// Generated by BUCKLESCRIPT VERSION 2.1.1, PLEASE EDIT WITH CARE
/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */
//# sourceURL=./node_modules/.docre/Docre__Writing_Documentation_md_CODE_BLOCK_8_alt.re_ppx.js
}
};
let nameMap = {
"./node_modules/.docre/Docre__Writing_Documentation_md_CODE_BLOCK_8_alt.re_ppx.js": 1
}
let require = (id) => {
if (!modules[id]) {
modules[id] = {exports: {}}
initializers[id](modules[id], modules[id].exports, require)
}
return modules[id].exports
};
require(1)})();</script>
</div>

<p>If there&#39;s no standalone comment at the top of a module, a &quot;default text&quot; is used, which looks like:</p>
<pre class='code-txt md'><code class='md'># [name of module]

This module does not have a toplevel documentation block.

@all</code></pre>

<p><code>@all</code> is a pragma (see below)</p>
<a href="#per-value-documentation" id="per-value-documentation"><h2>Per-value documentation</h2></a>

<p>A preceeding doc-comment will be parsed as markdown &amp; rendered.</p>
<div class='code-block' data-block-syntax="re">

<pre class='code' data-block-id='8' id='block-8'><code>/**
* Note: if the florp is invalid, this will generate a fresh bloop.
*
* ```re
* Js.log(florpToBloop(&quot;florp&quot;));
* ```
*/
let <span class='pattern-ident' data-type="'a => string">florpToBloop</span> = (<span class='pattern-ident' data-type="'a">florp</span>) =&gt; {
&quot;bloop&quot;
};</code></pre>



</div><div class='code-block' data-block-syntax="ml">

<pre class='code' data-block-id='8-alt' id='block-8-alt'><code>[@@@ocaml.ppx.context { cookies = [] }]
let <span class='pattern-ident' data-type="'a => string">florpToBloop</span> <span class='pattern-ident' data-type="'a">florp</span> = <span class='string' data-type="string">&quot;bloop&quot;</span>[@@ocaml.doc
&quot;\n * Note: if the florp is invalid, this will generate a fresh bloop.\n *\n * ```re\n * Js.log(florpToBloop(\&quot;florp\&quot;));\n * ```\n &quot;]</code></pre>



</div>

<a href="#pragmas" id="pragmas"><h2>Pragmas</h2></a>

<p>Pragmas are valid in the top-level documentation block only, not in per-value doc-comments. They must be on their own line, with a blank line above and below.</p>
<a href="#-doc-followed-by-a-comma-separated-list-of-names" id="-doc-followed-by-a-comma-separated-list-of-names"><h3><code>@doc</code> followed by a comma-separated list of names</h3></a>

<p>e.g. <code>@doc someItem, anotherItem</code></p>
<p>This lists the provided items in that order, along with their formatted doc comments.</p>
<a href="#-rest" id="-rest"><h3><code>@rest</code></h3></a>

<p>This lists all of the items that have not yet been listed via <code>@docs</code>. If you don&#39;t list all of the items exported by a module, <code>@rest</code> will be automatically added to the end of your documentation.</p>
<p><em>If you don&#39;t want something to show up in the documentation, don&#39;t expose it to the user in your module.</em></p>
<a href="#-all" id="-all"><h3><code>@all</code></h3></a>

<p>This just lists all of the exported items, along with their documentation. It is not recommended for general use, as it doesn&#39;t guide the user at all.</p>

</div>
<div class='right-blank'></div>
</div>
Expand Down
76 changes: 71 additions & 5 deletions docs/Writing Documentation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,82 @@

## Top-level module documentation

The first "standalone" comment in a module is treated as the main documentation block for that module.
The first "standalone" comment in a module is treated as the main documentation block for that module. Note the trailing semicolon, and that it starts with exactly two asterisks.

```re
Your top-level documentation should guide the user through the exposed types & values in your module, in order of importance. If the module exports a "main" function, that should be listed at the top, with lesser-used items listed later. It can be helpful to split the documentation into sections via markdown headers, especially if there are many items exported from a module.

> 🙏 Please include at least one example in the top-level documentation of each module. See "Interactive code snippets" for details.
```re;no-run
/**
* This is a standalone block
* # FlorpBloop
*
* This module is for turning florps into bloops.
*
* Here's how to use it:
* \```re
* open FlorpBloop;
* let bloop = florpToBloop(Florp.create());
* let florp = bloopToFlorp(bloop);
* assert(isValidFlorp(florp));
* \```
*
* ## General data transformation functions
*
* @doc florpToBloop, bloopToFlorp, convertManyFlorpsToBloops
*
* ## Less-used, but also helpful utilities
*
* @doc isValidFlorp, canConvertToBloop
*
* Note the trailing semicolon, and the two asterisks at the start (must be exactly two).
*/;
```

If there's no standalone comment at the top of a module, a "default text" is used, which looks like:

```md
# [name of module]

This module does not have a toplevel documentation block.

@all
```

`@all` is a pragma (see below)

## Per-value documentation

A preceeding doc-comment will be parsed as markdown & rendered.

```re;no-run
/**
* Note: if the florp is invalid, this will generate a fresh bloop.
*
* \```re
* Js.log(florpToBloop("florp"));
* \```
*/
let florpToBloop = (florp) => {
"bloop"
};
```

## Pragmas

Pragmas are valid in the top-level documentation block only, not in per-value doc-comments. They must be on their own line, with a blank line above and below.

### `@doc` followed by a comma-separated list of names

e.g. `@doc someItem, anotherItem`

This lists the provided items in that order, along with their formatted doc comments.

### `@rest`

This lists all of the items that have not yet been listed via `@docs`. If you don't list all of the items exported by a module, `@rest` will be automatically added to the end of your documentation.

*If you don't want something to show up in the documentation, don't expose it to the user in your module.*

### `@all`

## Per-value documentation
This just lists all of the exported items, along with their documentation. It is not recommended for general use, as it doesn't guide the user at all.
6 changes: 3 additions & 3 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -156,13 +156,13 @@

<p>get the binary (either by <a href="https://github.com/jaredly/docre/releases/" target="_blank" rel="noopener nofollow" title="" class="external-link">downloading it</a>, or building it yourself).</p>
<p>To build:</p>
<pre class='bash'><code class='bash'>npm install
<pre class='code-txt bash'><code class='bash'>npm install
npm start</code></pre>

<p>The binary is then in <code>./lib/bs/native/main.native</code>. You can run <code>./docre.sh</code>, which delegates to that.</p>
<a href="#common-options" id="common-options"><h3>Common options</h3></a>

<pre class='txt'><code class='txt'> --root (default: current directory)
<pre class='code-txt txt'><code class='txt'> --root (default: current directory)
expected to contain bsconfig.json, and bs-platform in the node_modules
--target (default: {root}/docs)
where we should write out the docs
Expand All @@ -177,7 +177,7 @@

<a href="#less-used-options" id="less-used-options"><h3>Less used options</h3></a>

<pre class='txt'><code class='txt'> --project-file (can be used multiple times)
<pre class='code-txt txt'><code class='txt'> --project-file (can be used multiple times)
specified as /abs/path/to/.cmt:rel/path/from/repo/root
--project-directory (can be used multiple times)
path/to/cmt/directory:rel/path/from/root
Expand Down
Loading

0 comments on commit bcee577

Please sign in to comment.