Overhaul gerbil reference documentation

ghost commented 5 years ago

Steadily move the docs into the following direction:

unified function signatures, return types and short parameter descriptions: see template below
descriptions for submodule functions: what are they doing? why are they there? safer alternatives? unsafe behaviour? deprecated?
provide example code: per function or a bigger usage example per submodule; similar to how the REPL looks
improve scheme markdown support in code blocks: gerbil-specific functions and syntax (#264)

Reference Documentation

[ ] Introduction

The Core Prelude

Core Expander Syntax

[ ] Top Forms
[ ] Expressions
[ ] Expander Hooks
[ ] Reserved Syntactic Tokens

Prelude Macros

[ ] Definition Forms
[ ] Binding Forms
[ ] Common Syntactic Sugar
[ ] MOP Macros
[ ] Pattern Matching
[ ] Macros for Syntax
[ ] Module Sugar

Runtime Symbol Bindings

Runtime [phi=0] Bindings

[ ] r5rs-runtime
[ ] host-runtime
[ ] aliases

Syntax [phi=1] Bindings

[ ] expander-runtime

More Gambit Symbols

[ ] bits
[ ] bytes
[ ] continuations
[ ] exceptions
[ ] fixnum
[ ] flonum
[ ] foreign
[ ] hash
[ ] hvectors
[ ] misc
[ ] os
[ ] ports
[ ] random
[ ] readtables
[ ] system
[ ] threads

Runtime Builtins

[ ] MOP
[ ] Special Objects
[ ] Hash Tables
[ ] Lists
[ ] Numerics
[ ] Symbols
[ ] Strings
[ ] Control Flow
[ ] Exception Objects
[ ] Miscellaneous Procedures
[ ] Syntax Objects
[ ] System Information
[ ] Thread Primitives

Expander Runtime

[ ] Syntax Errors
[ ] Syntax Objects
[ ] Identifiers
[ ] Utilities
[ ] syntax-case
[ ] Core Expander
[ ] Bindings
[ ] Expanders
[ ] Imports and Exports

The Standard Library

[ ] Description

Common Syntactic Sugar

[ ] try, with-destroy, defmethod/alias, ...

Exception Base Classes

[ ] exception, , io-error, ...

Command Line Argument Parsing

[ ] Interface
[ ] Example

Formatting

[ ] format, fprintf, printf, ...

Logging

[ ] current-logger, start-logger!, debug, ...

Sorting

[ ] sort, sort!, stable-sort, ...
[ ] how this relates to srfi-95 (sorting and merging)

Regular Expressions

[ ] pregexp, pregexp-match, pregexp-match-positions, ...

Generics

[ ] Overview
[ ] Macros
[ ] Predefined Types
[ ] Generic Object Types
[ ] Generic Method Objects
[ ] Syntax Bindings
[ ] Example

Generic Accessors and Mutators

[ ] ref, ref-set!, ~, ...

Iterators

[ ] Macros
[ ] Iterator Constructors
[ ] Iterator Protocol
[ ] Examples

Coroutines

[ ] Interface
[ ] Example

Events

[ ] Overview
[ ] Synchronization Primitives
[ ] Event Objects
[ ] Macros
[ ] Example

Actors

[ ] Overview
[ ] Basic Types
[ ] Exceptions
[ ] Message Primitives
[ ] Protocols
[ ] Syntax Bindings
[ ] RPC
[ ] RPC Server Protocol
[ ] RPC Wire Protocols
[ ] RPC Options
[ ] Example

HTTP requests

[x] Request API (thanks, zmyrgel)
[x] Request Objects (thanks, zmyrgel)

The Embedded HTTP Server

[ ] Server Interface
[ ] Request Multiplexer
[ ] Request Handler Interface
[ ] Server Configuration Options

Web Serving with FastCGI

[ ] Rack
[ ] FastCGI Interface

SQL Databases

[ ] Overview
[ ] Generic Database Interface
[ ] SQLite driver
[ ] PostgreSQL driver
[ ] MySQL driver
[ ] Connection Pools
[ ] Example

Key-Value Stores

[ ] LevelDB
[ ] LMDB

Network Programming with Sockets

[ ] Low Level Interface
[ ] Synchronous Socket Interface
[ ] The Socket Server

Protocol Buffers

[ ] Protobuf modules
[ ] Implementation Notes
[ ] I/O Procedures

Operating System Interface

[ ] Error Handling
[ ] File Descriptors
[ ] File Descriptor I/O
[ ] File Descriptor Control
[ ] Pipes
[ ] Signals
[ ] Signal Handling
[ ] PIDs
[ ] OS Specific APIs

Cryptography

[ ] Digests
[ ] Ciphers
[ ] Encryption and Decryption
[ ] HMAC
[ ] DH Key Exchange
[ ] etc

Text Encoding and Decoding

[ ] Base64
[ ] Base58
[ ] CSV
[ ] Hex
[ ] JSON
[ ] UTF8
[ ] YAML
[ ] Zlib

XML

[ ] Overview
[ ] Parsing
[ ] SXML Queries
[ ] Printing

Language Parsers

[ ] Overview
[ ] Regular Languages
[ ] Tokens, Locations, and Utilities
[ ] Character Streams
[ ] Lexing
[ ] Parsing
[ ] The Grammar Prelude

Miscellaneous

[x] Buffered channels
[x] Asynchronous Completions
[x] Thread Barriers
[x] Deques
[x] List utilities
[x] LRU caches
[x] Port utilities
[x] Priority Queues
[x] Process Utilities
[x] Simple Queues
[x] Red-Black Trees
[x] Sourceable Representation
[x] Type Descriptor Utilities.
[x] Shared-structure Equality.
[x] Shuffling
[x] String utilities
[x] Synchronized Data Structures.
[x] Text Utilities
[x] Thread utilities
[x] Timeouts
[x] UUIDs
[x] Functional utilities

Primitives for Lazy Evaluation

[ ] lazy, delay, force, ...

Primitives for Ambiguous Non-Deterministic Computation

[ ] Special Forms
[ ] Example

Syntax Parameters

[ ] Macros
[ ] Syntax Bindings

Utilities for FFI Programming

[ ] begin-ffi

SRFIs

[ ] SRFI 0 Feature-based conditional expansion construct
[ ] SRFI 1 List Library
[ ] SRFI 2 AND-LET*
[ ] SRFI 4 Homogeneous numeric vector datatypes
[ ] SRFI 6 Basic String Ports
[ ] SRFI 8 receive
[ ] SRFI 9 Defining Record Types
[ ] SRFI 13 String Library
[ ] SRFI 14 Character-Set Library
[ ] SRFI 16 Syntax for procedures of variable arity
[ ] SRFI 18 Multithreading support
[ ] SRFI 19 Time Data Types and Procedures
[ ] SRFI 21 Real-time multithreading support
[ ] SRFI 22 Running Scheme Scripts on Unix
[ ] SRFI 23 Error reporting mechanism
[ ] SRFI 26 Notation for Specializing Parameters without Currying
[ ] SRFI 27 Sources of Random Bits
[ ] SRFI 28 Basic Format Strings
[ ] SRFI 30 Nested Multi-line Comments
[ ] SRFI 31 A special form for recursive evaluation
[ ] SRFI 34 Exception Handling for Programs
[ ] SRFI 38 External Representation for Data With Shared Structure
[ ] SRFI 39 Parameter objects
[ ] SRFI 41 Streams
[ ] SRFI 42 Eager Comprehensions
[ ] SRFI 43 Vector Library
[ ] SRFI 45 Primitives for Expressing Iterative Lazy Algorithms
[ ] SRFI 48 Intermediate Format Strings
[ ] SRFI 60 Integers as Bits
[ ] SRFI 62 S-expression comments
[ ] SRFI 78 Lightweight testing
[ ] SRFI 87 => in case clauses
[ ] SRFI 88 Keyword Objects
[ ] SRFI 95 Sorting and Merging
[ ] SRFI 101 Purely Functional Random-Access Pairs and Lists
[ ] SRFI 111 Boxes
[ ] SRFI 113 Sets and bags
[ ] SRFI 116 Immutable List Library
[ ] SRFI 117 Queues based on lists
[ ] SRFI 121 Generators
[ ] SRFI 124 Ephemerons
[ ] SRFI 125 Intermediate hash tables
[ ] SRFI 127 Lazy Sequences
[ ] SRFI 128 Comparators (reduced)
[ ] SRFI 132 Sort Libraries
[ ] SRFI 133 Vector Library (R7RS-compatible)
[ ] SRFI 134 Immutable Deques
[ ] SRFI 135 Immutable Texts

Testing

[ ] Overview
[ ] Interface
[ ] Example

Debugging

[ ] Heap debugging utilities
[ ] Memory leak debugging utilities
[ ] Thread debugging utilities

Build Tool

[ ] Overview
[ ] Interface
[ ] Standard Package Build Script

ghost commented 5 years ago

Documentation template:

## submodule
::: tip To use the bindings from this module:
``` scheme
(import :std/...)
```
:::

### function
``` scheme
(function param [opt-param = #f] [key-param: eqv] ...) -> ret1 | ret2 | ...

  param     := param description ...
  opt-param := param description ...
  key-param := param description ...
```

Function description; *param* highlighted; inline `code`

::: tip Examples:
``` scheme
> (function  ...)
ret
```
:::

zmyrgel commented 5 years ago

The template should specify how aliases should be documented. Should alias procedures be grouped in same documentation block or kept separately. If separate, keep their description short or duplicate the docs. Link the entry to original?

ghost commented 5 years ago

Yes, that's something I'm not too happy with either. Also, there are defalias, defmethod-alias, defmethods and re-exports of unsafe variants (e.g. object-type), all of which are not explicitly listed in the template above.

In misc.md I've documented an alias right after its original function in a fresh paragraph so that vuepress shows it in the sidebar as well as the search bar. See pr for example.

Feel free to propose and push for a semi-consistent way to declare all of them. I'm not the head of documentation, just a regular user. 😃

But yes, linking to the original would be desirable indeed.

belmarca commented 5 years ago

See https://cons.io/reference/misc.html#bytes for another example.

belmarca commented 5 years ago

Is there any interest in having the docs in the code itself?

ghost commented 5 years ago

Parsable documentation with embedded code examples that function as unit tests would absolutely be of interest. Would eliminate a lot of minor inconsistencies thoughout the docs.

But since I've slacked off for a while now I'll instead concentrate on getting rid of these nasty "Please document me!" prompts. :)

arichiardi commented 4 years ago

Ooooooh nice! I was looking for more docs on the actors, especially the remote ones, the index here looks awesome, just stopped by to say "keep up the good job!" 😃

vyzo commented 4 years ago

Yeah, I am planning to document the actor library in the not so distant future!

mighty-gerbils / gerbil