Package-level documentation (#3281)

STYLE_GUIDE.md

@@ -556,6 +556,8 @@ fun mod_checked
 
 ## Documentation
 
+### Public Functions and Types
+
 Public functions and types must include a triple-quoted docstring unless it is self-explanatory to anyone with the most basic knowledge of the domain. Markdown is used for formatting. The `"""` tokens are placed on their own lines, even when the entire docstring could fit on a single line with the `"""` tokens.
 
 ```pony
@@ -577,6 +579,10 @@ primitive Format
   """
 ```
 
+### Package-level documentation
+
+Package-level documentation should be placed in a file called `<PACKAGE>.pony` within a triple-quoted docstring at the top of the file. This same file may contain additional content if such organization makes sense for the package.
+
 ## Comments
 
 Single line comments will have exactly one space between the `//` token and the beginning of the comment message. This single space may only be omitted if the comment only contains valid Pony code. Single line comments that continue a previous comment have the same spacing requirements. No such restrictions are placed on multiline comments between the `/*` and `*/` tokens.

packages/bureaucracy/bureaucracy.pony

@@ -0,0 +1,17 @@
+"""
+# Bureaucracy package
+
+It happens to almost every program. It starts small, tiny if you will, like a
+village where every actor knows every other actor and shutdown is easy. One day
+you realize your program is no longer a cute seaside hamlet, its a bustling
+metropolis and you are doing way too much work to keep track of everything.
+What do you do? Call for a little bureaucracy.
+
+The bureaucracy contains objects designed to ease your bookkeeping burdens.
+Need to shutdown a number of actors together? Check out `Custodian`. Need
+to keep track of a lot of stuff and be able to look it up by name? Check out
+`Registrar`.
+
+Put bureaucracy to use today and before long, your sprawling metropolis of a
+code base will be manageable again in no time.
+"""

packages/bureaucracy/custodian.pony

@@ -1,21 +1,3 @@
-"""
-# Bureaucracy package
-
-It happens to almost every program. It starts small, tiny if you will, like a
-village where every actor knows every other actor and shutdown is easy. One day
-you realize your program is no longer a cute seaside hamlet, its a bustling
-metropolis and you are doing way too much work to keep track of everything.
-What do you do? Call for a little bureaucracy.
-
-The bureaucracy contains objects designed to ease your bookkeeping burdens.
-Need to shutdown a number of actors together? Check out `Custodian`. Need
-to keep track of a lot of stuff and be able to look it up by name? Check out
-`Registrar`.
-
-Put bureaucracy to use today and before long, your sprawling metropolis of a
-code base will be manageable again in no time.
-"""
-
 use "collections"
 
 actor Custodian

packages/capsicum/capsicum.pony

@@ -0,0 +1,5 @@
+"""
+# Capsicum package
+
+Access to Capsicum capabilities for UNIX systems -- primarily in use by BSD-based systems.
+"""

packages/collections/collections.pony

@@ -0,0 +1,20 @@
+"""
+# Collections package
+
+The Collections package provides a variety of collection classes, 
+including map, set, range, heap, ring buffer, list, and flags.
+
+`Map` - Hashmap by strutural equality (use `MapIs` for identity equality).
+
+`Set` - A set built on top of `Map` using structural equility (use `SetIs` for identity equality).
+
+`Range` - Iterate over a range of numbers with optional step size.
+
+`BinaryHeap` - A priority queue implemented as a binary heap -- use a `BinaryHeapPriority` parameter to determine priority.
+
+`RingBuffer` - A ring buffer with fixed size.
+
+`List` - A doubly linked list.
+
+`Flags` - A set of single bit flags (size determined upon creation).
+"""

packages/collections/persistent/persistent.pony

@@ -1,15 +1,15 @@
 """
 # Persistent Collections Package
 
-List - A persistent list with functional transformations.
+`List` - A persistent list with functional transformations.
 
-Map - A persistent map based on the Compressed Hash Array Mapped Prefix-tree
+`Map` - A persistent map based on the Compressed Hash Array Mapped Prefix-tree
 from 'Optimizing Hash-Array Mapped Tries for Fast and Lean Immutable JVM
 Collections' by Michael J. Steindorfer and Jurgen J. Vinju.
 
-Set - A persistent set implemented as a persistent map of an alias of a type
+`Set` - A persistent set implemented as a persistent map of an alias of a type
 to itself.
 
-Vec - A persistent vector based on the Hash Array Mapped Trie from 'Ideal Hash
+`Vec` - A persistent vector based on the Hash Array Mapped Trie from 'Ideal Hash
 Trees' by Phil Bagwell.
 """

packages/math/fibonacci.pony

@@ -1,17 +1,3 @@
-"""
-# Math package
-
-Given the name `Math` for this package, you'd expect it have a broad and grand
-scope. Surprise! Not currently. However, we do have the most useful of all
-programming language math constructs: fibonacci!
-
-People like to make fun of fibonacci but let's face it, no fibonacci, no
-benchmarks. We hear from some of our engineer friends that math is very
-important to programming, we call upon that particular class of engineer friends
-to help us fill out this package with more maths than you can shake a stick at.
-Btw, in case you are wondering, yes we can shake a stick at a lot of maths.
-"""
-
 class Fibonacci[A: (Integer[A] val & Unsigned) = U64] is Iterator[A]
   """
   Useful for microbenchmarks to impress your friends. Look y'all, Pony goes

packages/math/math.pony

@@ -0,0 +1,13 @@
+"""
+# Math package
+
+Given the name `Math` for this package, you'd expect it have a broad and grand
+scope. Surprise! Not currently. However, we do have the most useful of all
+programming language math constructs: fibonacci!
+
+People like to make fun of fibonacci but let's face it, no fibonacci, no
+benchmarks. We hear from some of our engineer friends that math is very
+important to programming, we call upon that particular class of engineer friends
+to help us fill out this package with more maths than you can shake a stick at.
+Btw, in case you are wondering, yes we can shake a stick at a lot of maths.
+"""

packages/process/process.pony

@@ -0,0 +1,98 @@
+"""
+# Process package
+
+The Process package provides support for handling Unix style processes.
+For each external process that you want to handle, you need to create a
+`ProcessMonitor` and a corresponding `ProcessNotify` object. Each
+ProcessMonitor runs as it own actor and upon receiving data will call its
+corresponding `ProcessNotify`'s method.
+
+## Example program
+
+The following program will spawn an external program and write to it's
+STDIN. Output received on STDOUT of the child process is forwarded to the
+ProcessNotify client and printed.
+
+```pony
+use "process"
+use "files"
+
+actor Main
+  new create(env: Env) =>
+    // create a notifier
+    let client = ProcessClient(env)
+    let notifier: ProcessNotify iso = consume client
+    // define the binary to run
+    try
+      let path = FilePath(env.root as AmbientAuth, "/bin/cat")?
+      // define the arguments; first arg is always the binary name
+      let args: Array[String] val = ["cat"]
+      // define the environment variable for the execution
+      let vars: Array[String] val = ["HOME=/"; "PATH=/bin"]
+      // create a ProcessMonitor and spawn the child process
+      let auth = env.root as AmbientAuth
+      let pm: ProcessMonitor = ProcessMonitor(auth, auth, consume notifier,
+      path, args, vars)
+      // write to STDIN of the child process
+      pm.write("one, two, three")
+      pm.done_writing() // closing stdin allows cat to terminate
+    else
+      env.out.print("Could not create FilePath!")
+    end
+
+// define a client that implements the ProcessNotify interface
+class ProcessClient is ProcessNotify
+  let _env: Env
+
+  new iso create(env: Env) =>
+    _env = env
+
+  fun ref stdout(process: ProcessMonitor ref, data: Array[U8] iso) =>
+    let out = String.from_array(consume data)
+    _env.out.print("STDOUT: " + out)
+
+  fun ref stderr(process: ProcessMonitor ref, data: Array[U8] iso) =>
+    let err = String.from_array(consume data)
+    _env.out.print("STDERR: " + err)
+
+  fun ref failed(process: ProcessMonitor ref, err: ProcessError) =>
+    _env.out.print(err.string())
+
+  fun ref dispose(process: ProcessMonitor ref, child_exit_status: ProcessExitStatus) =>
+    let code: I32 = consume child_exit_code
+    match child_exit_status
+    | let exited: Exited =>
+      _env.out.print("Child exit code: " + exited.exit_code().string())
+    | let signaled: Signaled =>
+      _env.out.print("Child terminated by signal: " + signaled.signal().string())
+    end
+```
+
+## Process portability
+
+The ProcessMonitor supports spawning processes on Linux, FreeBSD, OSX and
+Windows.
+
+## Shutting down ProcessMonitor and external process
+
+When a process is spawned using ProcessMonitor, and it is not necessary to
+communicate to it any further using `stdin` and `stdout` or `stderr`, calling
+[done_writing()](process-ProcessMonitor.md#done_writing) will close stdin to
+the child process. Processes expecting input will be notified of an `EOF` on
+their `stdin` and can terminate.
+
+If a running program needs to be canceled and the
+[ProcessMonitor](process-ProcessMonitor.md) should be shut down, calling
+[dispose](process-ProcessMonitor.md#dispose) will terminate the child process
+and clean up all resources.
+
+Once the child process is detected to be closed, the process exit status is
+retrieved and [ProcessNotify.dispose](process-ProcessNotify.md#dispose) is
+called.
+
+The process exit status can be either an instance of
+[Exited](process-Exited.md) containing the process exit code in case the
+program exited on its own, or (only on posix systems like linux, osx or bsd) an
+instance of [Signaled](process-Signaled.md) containing the signal number that
+terminated the process.
+"""

packages/process/process_monitor.pony

@@ -1,101 +1,3 @@
-"""
-# Process package
-
-The Process package provides support for handling Unix style processes.
-For each external process that you want to handle, you need to create a
-`ProcessMonitor` and a corresponding `ProcessNotify` object. Each
-ProcessMonitor runs as it own actor and upon receiving data will call its
-corresponding `ProcessNotify`'s method.
-
-## Example program
-
-The following program will spawn an external program and write to it's
-STDIN. Output received on STDOUT of the child process is forwarded to the
-ProcessNotify client and printed.
-
-```pony
-use "process"
-use "files"
-
-actor Main
-  new create(env: Env) =>
-    // create a notifier
-    let client = ProcessClient(env)
-    let notifier: ProcessNotify iso = consume client
-    // define the binary to run
-    try
-      let path = FilePath(env.root as AmbientAuth, "/bin/cat")?
-      // define the arguments; first arg is always the binary name
-      let args: Array[String] val = ["cat"]
-      // define the environment variable for the execution
-      let vars: Array[String] val = ["HOME=/"; "PATH=/bin"]
-      // create a ProcessMonitor and spawn the child process
-      let auth = env.root as AmbientAuth
-      let pm: ProcessMonitor = ProcessMonitor(auth, auth, consume notifier,
-      path, args, vars)
-      // write to STDIN of the child process
-      pm.write("one, two, three")
-      pm.done_writing() // closing stdin allows cat to terminate
-    else
-      env.out.print("Could not create FilePath!")
-    end
-
-// define a client that implements the ProcessNotify interface
-class ProcessClient is ProcessNotify
-  let _env: Env
-
-  new iso create(env: Env) =>
-    _env = env
-
-  fun ref stdout(process: ProcessMonitor ref, data: Array[U8] iso) =>
-    let out = String.from_array(consume data)
-    _env.out.print("STDOUT: " + out)
-
-  fun ref stderr(process: ProcessMonitor ref, data: Array[U8] iso) =>
-    let err = String.from_array(consume data)
-    _env.out.print("STDERR: " + err)
-
-  fun ref failed(process: ProcessMonitor ref, err: ProcessError) =>
-    _env.out.print(err.string())
-
-  fun ref dispose(process: ProcessMonitor ref, child_exit_status: ProcessExitStatus) =>
-    let code: I32 = consume child_exit_code
-    match child_exit_status
-    | let exited: Exited =>
-      _env.out.print("Child exit code: " + exited.exit_code().string())
-    | let signaled: Signaled =>
-      _env.out.print("Child terminated by signal: " + signaled.signal().string())
-    end
-```
-
-## Process portability
-
-The ProcessMonitor supports spawning processes on Linux, FreeBSD, OSX and
-Windows.
-
-## Shutting down ProcessMonitor and external process
-
-When a process is spawned using ProcessMonitor, and it is not necessary to
-communicate to it any further using `stdin` and `stdout` or `stderr`, calling
-[done_writing()](process-ProcessMonitor.md#done_writing) will close stdin to
-the child process. Processes expecting input will be notified of an `EOF` on
-their `stdin` and can terminate.
-
-If a running program needs to be canceled and the
-[ProcessMonitor](process-ProcessMonitor.md) should be shut down, calling
-[dispose](process-ProcessMonitor.md#dispose) will terminate the child process
-and clean up all resources.
-
-Once the child process is detected to be closed, the process exit status is
-retrieved and [ProcessNotify.dispose](process-ProcessNotify.md#dispose) is
-called.
-
-The process exit status can be either an instance of
-[Exited](process-Exited.md) containing the process exit code in case the
-program exited on its own, or (only on posix systems like linux, osx or bsd) an
-instance of [Signaled](process-Signaled.md) containing the signal number that
-terminated the process.
-"""
 use "backpressure"
 use "collections"
 use "files"