Overhaul gerbil reference documentation #263

New issue

2019-05-23T17:42:28Z

ghost commented

2019-05-23 17:42:28 +00:00

(Migrated from github.com)

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

Request API (thanks, zmyrgel)
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

Network REPL
URIs [RFC3986]
Internet Addresses
Binary I/O Buffers
SASL authentication
SOCKS Proxy Client.
Websocket Client
WAMP Client

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

Buffered channels
Asynchronous Completions
Thread Barriers
Deques
List utilities
LRU caches
Port utilities
Priority Queues
Process Utilities
Simple Queues
Red-Black Trees
Sourceable Representation
Type Descriptor Utilities.
Shared-structure Equality.
Shuffling
String utilities
Synchronized Data Structures.
Text Utilities
Thread utilities
Timeouts
UUIDs
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

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, <error>, 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 ## Network related Libraries - [ ] Network REPL - [ ] URIs [RFC3986] - [ ] Internet Addresses - [ ] Binary I/O Buffers - [ ] SASL authentication - [ ] SOCKS Proxy Client. - [ ] Websocket Client - [ ] WAMP Client ## 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

👍 1

ghost commented

2019-05-23 17:48:11 +00:00

(Migrated from github.com)

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
```
:::

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

2019-07-14 07:45:46 +00:00

(Migrated from github.com)

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

2019-07-14 11:46:38 +00:00

(Migrated from github.com)

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.

Yes, that's something I'm not too happy with either. Also, there are `defalias`, [`defmethod-alias`](https://cons.io/reference/sugar.html#defmethod-alias), [`defmethods`](https://cons.io/reference/misc.html#channel-destructor) and re-exports of unsafe variants (e.g. [object-type](https://cons.io/reference/misc.html#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`](https://cons.io/reference/misc.html#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

2019-08-08 14:19:07 +00:00

(Migrated from github.com)

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

belmarca commented

2019-09-11 15:11:21 +00:00

(Migrated from github.com)

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

👀 1

ghost commented

2019-09-19 08:25:28 +00:00

(Migrated from github.com)

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. :)

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

2019-10-11 02:21:32 +00:00

(Migrated from github.com)

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!" 😃

👍 3

vyzo commented

2019-10-11 15:30:15 +00:00

(Migrated from github.com)

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

👍 1

Sign in to join this conversation.