Add improved docs

Author: wooorm

index.js

@@ -1,7 +1,8 @@
 /**
  * @typedef {import('./lib/parser.js').Buf} Value
  * @typedef {import('./lib/parser.js').BufferEncoding} BufferEncoding
- * @typedef {import('./lib/compiler.js').Options} Options
+ * @typedef {import('./lib/compiler.js').Options} CompileOptions
+ * @typedef {import('./lib/from-mdast.js').Options} FromMdastOptions
  */
 
 export {buffer} from './lib/buffer.js'

lib/buffer.js

@@ -8,13 +8,15 @@ import {compiler} from './compiler.js'
 import {parser} from './parser.js'
 
 /**
- * @param {Buf} buf
- *   String or buffer to parse.
+ * Compile gemtext to HTML.
+ *
+ * @param {Buf} doc
+ *   Gemtext to parse
  * @param {BufferEncoding} [encoding]
  *   Character encoding to understand `doc` as when it’s a `Buffer`.
  * @param {Options} [options]
  *   Compile configuration (optional).
  */
-export function buffer(buf, encoding, options) {
-  return compiler(options)(parser()(buf, encoding, true))
+export function buffer(doc, encoding, options) {
+  return compiler(options)(parser()(doc, encoding, true))
 }

lib/from-gemtext.js

@@ -14,7 +14,7 @@
 import {parser} from './parser.js'
 
 /**
- * Parse gemtext to into an AST (gast).
+ * Parse gemtext to an AST (gast).
  * `doc` and `encoding` are the same as the buffering interface.
  *
  * @param {Buf} doc

lib/from-mdast.js

@@ -36,10 +36,6 @@
  * @typedef {import('unist').Node} UnistNode
  * @typedef {import('unist').Parent} UnistParent
  *
- * @typedef Options
- * @property {boolean} [tight=false]
- * @property {boolean} [endlinks=false]
- *
  * @typedef Defined
  * @property {Record<string, MdastDefinition>} definition
  * @property {Record<string, MdastFootnoteDefinition>} footnoteDefinition
@@ -70,6 +66,15 @@
  * @property {Queues} queues
  * @property {number} link
  * @property {number} footnote
+ *
+ * @typedef Options
+ *   Configuration (optional).
+ * @property {boolean} [tight=false]
+ *   Do not put blank lines between blocks.
+ *   The default is to place breaks between each block (paragraph, heading, etc).
+ * @property {boolean} [endlinks=false]
+ *   Place links at the end of the document.
+ *   The default is to place links before the next heading.
  */
 
 import {visit} from 'unist-util-visit'
@@ -123,8 +128,12 @@ function handle(node, context) {
 }
 
 /**
+ * Transform mdast to gast.
+ *
  * @param {MdastNode} tree
+ *   mdast tree.
  * @param {Options} [options]
+ *   Configuration (optional).
  * @returns {Array<GastContent>|GastNode|string|void}
  */
 export function fromMdast(tree, options) {