improve documentation formatting

Summary:
- add missing backticks. This isn't just fixed-width: it makes them links on docs.hhvm.com
 - format lists as lists: newlines aren't preserved in markdown (though codex preserves them)
Closes #42

Reviewed By: savil

Differential Revision: D6613603

Pulled By: savil

fbshipit-source-id: 60a389cdfed60b5c34691dc22e38a0160a334139

src/c/async.php

@@ -19,7 +19,7 @@
  * Returns the first element of the result of the given Awaitable, or null if
  * the Traversable is empty.
  *
- * For non-Awaitable Traversables, see C\first.
+ * For non-Awaitable Traversables, see `C\first`.
  */
 async function first_async<T>(
   Awaitable<Traversable<T>> $awaitable,
@@ -32,7 +32,7 @@
  * Returns the first element of the result of the given Awaitable, or throws if
  * the Traversable is empty.
  *
- * For non-Awaitable Traversables, see C\firstx.
+ * For non-Awaitable Traversables, see `C\firstx`.
  */
 async function firstx_async<T>(
   Awaitable<Traversable<T>> $awaitable,

src/c/introspect.php

@@ -20,7 +20,7 @@
  * given Traversable. If no predicate is provided, it defaults to casting the
  * element to bool.
  *
- * If you're looking for C\none, use !C\any.
+ * If you're looking for `C\none`, use `!C\any`.
  */
 function any<T>(
   Traversable<T> $traversable,

src/c/select.php

@@ -49,10 +49,10 @@ function find_key<Tk, Tv>(
  * Returns the first element of the given Traversable, or null if the
  * Traversable is empty.
  *
- * For non-empty Traversables, see C\firstx.
- * For possibly null Traversables, see C\nfirst.
- * For single-element Traversables, see C\onlyx.
- * For Awaitables that yield Traversables, see C\first_async.
+ * - For non-empty Traversables, see `C\firstx`.
+ * - For possibly null Traversables, see `C\nfirst`.
+ * - For single-element Traversables, see `C\onlyx`.
+ * - For Awaitables that yield Traversables, see `C\first_async`.
  */
 function first<T>(
   Traversable<T> $traversable,
@@ -67,10 +67,10 @@ function first<T>(
  * Returns the first element of the given Traversable, or throws if the
  * Traversable is empty.
  *
- * For possibly empty Traversables, see C\first.
- * For possibly null Traversables, see C\nfirst.
- * For single-element Traversables, see C\onlyx.
- * For Awaitables that yield Traversables, see C\firstx_async.
+ * - For possibly empty Traversables, see `C\first`.
+ * - For possibly null Traversables, see `C\nfirst`.
+ * - For single-element Traversables, see `C\onlyx`.
+ * - For Awaitables that yield Traversables, see `C\firstx_async`.
  */
 function firstx<T>(
   Traversable<T> $traversable,
@@ -85,7 +85,7 @@ function firstx<T>(
  * Returns the first key of the given KeyedTraversable, or null if the
  * KeyedTraversable is empty.
  *
- * For non-empty Traversables, see C\first_keyx.
+ * For non-empty Traversables, see `C\first_keyx`.
  */
 function first_key<Tk, Tv>(
   KeyedTraversable<Tk, Tv> $traversable,
@@ -102,7 +102,7 @@ function first_key<Tk, Tv>(
  * Returns the first key of the given KeyedTraversable, or throws if the
  * KeyedTraversable is empty.
  *
- * For possibly empty Traversables, see C\first_key.
+ * For possibly empty Traversables, see `C\first_key`.
  */
 function first_keyx<Tk, Tv>(
   KeyedTraversable<Tk, Tv> $traversable,
@@ -117,8 +117,8 @@ function first_keyx<Tk, Tv>(
  * Returns the last element of the given Traversable, or null if the
  * Traversable is empty.
  *
- * For non-empty Traversables, see C\lastx.
- * For single-element Traversables, see C\onlyx.
+ * - For non-empty Traversables, see `C\lastx`.
+ * - For single-element Traversables, see `C\onlyx`.
  */
 function last<Tv>(
   Traversable<Tv> $traversable,
@@ -138,8 +138,8 @@ function last<Tv>(
  * Returns the last element of the given Traversable, or throws if the
  * Traversable is empty.
  *
- * For possibly empty Traversables, see C\last.
- * For single-element Traversables, see C\onlyx.
+ * - For possibly empty Traversables, see `C\last`.
+ * - For single-element Traversables, see `C\onlyx`.
  */
 function lastx<Tv>(Traversable<Tv> $traversable): Tv {
   // There is no way to directly check whether an Iterable is empty,
@@ -168,7 +168,7 @@ function lastx<Tv>(Traversable<Tv> $traversable): Tv {
  * Returns the last key of the given KeyedTraversable, or null if the
  * KeyedTraversable is empty.
  *
- * For non-empty Traversables, see C\last_keyx.
+ * For non-empty Traversables, see `C\last_keyx`.
  */
 function last_key<Tk, Tv>(
   KeyedTraversable<Tk, Tv> $traversable,
@@ -192,7 +192,7 @@ function last_key<Tk, Tv>(
  * Returns the last key of the given KeyedTraversable, or throws if the
  * KeyedTraversable is empty.
  *
- * For possibly empty Traversables, see C\last_key.
+ * For possibly empty Traversables, see `C\last_key`.
  */
 function last_keyx<Tk, Tv>(
   KeyedTraversable<Tk, Tv> $traversable,
@@ -206,9 +206,9 @@ function last_keyx<Tk, Tv>(
  * Returns the first element of the given Traversable, or null if the
  * Traversable is null or empty.
  *
- * For non-null Traversables, see C\first.
- * For non-empty Traversables, see C\firstx.
- * For single-element Traversables, see C\onlyx.
+ * - For non-null Traversables, see `C\first`.
+ * - For non-empty Traversables, see `C\firstx`.
+ * - For single-element Traversables, see `C\onlyx`.
  */
 function nfirst<T>(
   ?Traversable<T> $traversable,
@@ -225,7 +225,7 @@ function nfirst<T>(
  * Returns the first and only element of the given Traversable, or throws if the
  * Traversable is empty.
  *
- * For Traversables with more than one element, see C\firstx.
+ * For Traversables with more than one element, see `C\firstx`.
  */
 function onlyx<T>(
   Traversable<T> $traversable,

src/dict/order.php

@@ -32,8 +32,8 @@ function reverse<Tk as arraykey, Tv>(
  * optional comparator function isn't provided, the values will be sorted in
  * ascending order.
  *
- * To sort by some computable property of each value, see `Dict\sort_by()`.
- * To sort by the keys of the KeyedTraversable, see `Dict\sort_by_key()`.
+ * - To sort by some computable property of each value, see `Dict\sort_by()`.
+ * - To sort by the keys of the KeyedTraversable, see `Dict\sort_by_key()`.
  */
 function sort<Tk as arraykey, Tv>(
   KeyedTraversable<Tk, Tv> $traversable,
@@ -54,8 +54,8 @@ function sort<Tk as arraykey, Tv>(
  * comparator function isn't provided, the values will be sorted in ascending
  * order of scalar key.
  *
- * To sort by the values of the KeyedTraversable, see `Dict\sort()`.
- * To sort by the keys of the KeyedTraversable, see `Dict\sort_by_key()`.
+ * - To sort by the values of the KeyedTraversable, see `Dict\sort()`.
+ * - To sort by the keys of the KeyedTraversable, see `Dict\sort_by_key()`.
  */
 function sort_by<Tk as arraykey, Tv, Ts>(
   KeyedTraversable<Tk, Tv> $traversable,
@@ -76,8 +76,8 @@ function sort_by<Tk as arraykey, Tv, Ts>(
  * optional comparator function isn't provided, the keys will be sorted in
  * ascending order.
  *
- * To sort by the values of the KeyedTraversable, see `Dict\sort()`.
- * To sort by some computable property of each value, see `Dict\sort_by()`.
+ * - To sort by the values of the KeyedTraversable, see `Dict\sort()`.
+ * - To sort by some computable property of each value, see `Dict\sort_by()`.
  */
 function sort_by_key<Tk as arraykey, Tv>(
   KeyedTraversable<Tk, Tv> $traversable,

src/dict/select.php

@@ -60,8 +60,8 @@ function drop<Tk as arraykey, Tv>(
  * Returns a new dict containing only the values for which the given predicate
  * returns `true`. The default predicate is casting the value to boolean.
  *
- * To remove null values in a typechecker-visible way, see `Dict\filter_nulls()`.
- * To use an async predicate, see `Dict\filter_async()`.
+ * - To remove null values in a typechecker-visible way, see `Dict\filter_nulls()`.
+ * - To use an async predicate, see `Dict\filter_async()`.
  */
 function filter<Tk as arraykey, Tv>(
   KeyedTraversable<Tk, Tv> $traversable,

src/dict/transform.php

@@ -99,9 +99,9 @@ function flip<Tk, Tv as arraykey>(
  * Returns a new dict where each value is the result of calling the given
  * function on the corresponding key.
  *
- * To use an async function, see `Dict\from_keys_async()`.
- * To create a dict from values, see `Dict\from_values()`.
- * To create a dict from key/value pairs, see `Dict\from_entries()`.
+ * - To use an async function, see `Dict\from_keys_async()`.
+ * - To create a dict from values, see `Dict\from_values()`.
+ * - To create a dict from key/value pairs, see `Dict\from_entries()`.
  */
 function from_keys<Tk as arraykey, Tv>(
   Traversable<Tk> $keys,
@@ -116,11 +116,13 @@ function from_keys<Tk as arraykey, Tv>(
 
 /**
  * Returns a new dict where each mapping is defined by the given key/value
- * tuples. In the case of duplicate keys, later values will overwrite the
+ * tuples.
+ *
+ * In the case of duplicate keys, later values will overwrite the
  * previous ones.
  *
- * To create a dict from keys, see `Dict\from_keys()`.
- * To create a dict from values, see `Dict\from_values()`.
+ * - To create a dict from keys, see `Dict\from_keys()`.
+ * - To create a dict from values, see `Dict\from_values()`.
  */
 function from_entries<Tk as arraykey, Tv>(
   Traversable<(Tk, Tv)> $entries,
@@ -134,11 +136,13 @@ function from_entries<Tk as arraykey, Tv>(
 
 /**
  * Returns a new dict keyed by the result of calling the given function on each
- * corresponding value. In the case of duplicate keys, later values will
+ * corresponding value.
+ *
+ * In the case of duplicate keys, later values will
  * overwrite the previous ones.
  *
- * To create a dict from keys, see `Dict\from_keys()`.
- * To create a dict from key/value pairs, see `Dict\from_entries()`.
+ * - To create a dict from keys, see `Dict\from_keys()`.
+ * - To create a dict from key/value pairs, see `Dict\from_entries()`.
  */
 function from_values<Tk as arraykey, Tv>(
   Traversable<Tv> $values,
@@ -155,6 +159,7 @@ function from_values<Tk as arraykey, Tv>(
   * Returns a new dict where
   *  - keys are the results of the given function called on the given values.
   *  - values are vecs of original values that all produced the same key.
+  *
   * If a value produces a null key, it's omitted from the result.
   */
 function group_by<Tk as arraykey, Tv>(

src/math/compare.php

@@ -14,8 +14,8 @@
 /**
  * Returns the largest of all input numbers.
  *
- * To find the smallest number, see `Math\minva()`.
- * For Traversables, see `Math\max()`.
+ * - To find the smallest number, see `Math\minva()`.
+ * - For Traversables, see `Math\max()`.
  */
 function maxva<T as num>(
   T $first,
@@ -33,8 +33,8 @@ function maxva<T as num>(
 /**
  * Returns the smallest of all input numbers.
  *
- * To find the largest number, see `Math\maxva()`.
- * For Traversables, see `Math\min()`.
+ * - To find the largest number, see `Math\maxva()`.
+ * - For Traversables, see `Math\min()`.
  */
 function minva<T as num>(
   T $first,

src/math/compute.php

@@ -26,8 +26,8 @@ function abs<T as num>(T $number): T {
  * letters a-z are used for digits for bases greater than 10. The conversion is
  * done to arbitrary precision.
  *
- * To convert a string in some base to an int, see `Math\from_base()`.
- * To convert an int to a string in some base, see `Math\to_base()`.
+ * - To convert a string in some base to an int, see `Math\from_base()`.
+ * - To convert an int to a string in some base, see `Math\to_base()`.
  */
 function base_convert(string $value, int $from_base, int $to_base): string {
   invariant(
@@ -95,8 +95,8 @@ function ceil(num $value): float {
 /**
  * Returns the cosine of `$arg`.
  *
- * To find the sine, see `Math\sin()`.
- * To find the tangent, see `Math\tan()`.
+ * - To find the sine, see `Math\sin()`.
+ * - To find the tangent, see `Math\tan()`.
  */
 function cos(num $arg): float {
   return \cos($arg);
@@ -132,10 +132,10 @@ function exp(num $arg): float {
 /**
  * Returns the largest integer value less than or equal to `$value`.
  *
- * To find the smallest integer value greater than or equal to `$value`, see
- * `Math\ceil()`.
- * To find the largest integer value less than or equal to a ratio, see
- * `Math\int_div()`.
+ * - To find the smallest integer value greater than or equal to `$value`, see
+ *   `Math\ceil()`.
+ * - To find the largest integer value less than or equal to a ratio, see
+ *   `Math\int_div()`.
  */
 function floor(num $value): float {
   return \floor($value);
@@ -184,8 +184,8 @@ function round(
 /**
  * Returns the sine of $arg.
  *
- * To find the cosine, see `Math\cos()`.
- * To find the tangent, see `Math\tan()`.
+ * - To find the cosine, see `Math\cos()`.
+ * - To find the tangent, see `Math\tan()`.
  */
 function sin(num $arg): float {
   return \sin($arg);
@@ -202,8 +202,8 @@ function sqrt(num $arg): float {
 /**
  * Returns the tangent of `$arg`.
  *
- * To find the cosine, see `Math\cos()`.
- * To find the sine, see `Math\sin()`.
+ * - To find the cosine, see `Math\cos()`.
+ * - To find the sine, see `Math\sin()`.
  */
 function tan(num $arg): float {
   return \tan($arg);

src/math/containers.php

@@ -16,8 +16,8 @@
  * Returns the largest element of the given Traversable, or null if the
  * Traversable is empty.
  *
- * For a known number of inputs, see `Math\maxva()`.
- * To find the smallest number, see `Math\min()`.
+ * - For a known number of inputs, see `Math\maxva()`.
+ * - To find the smallest number, see `Math\min()`.
  */
 function max<T as num>(
   Traversable<T> $numbers,
@@ -59,9 +59,9 @@ function max_by<T>(
 /**
  * Returns the arithmetic mean of the numbers in the given container.
  *
- * To find the sum, see `Math\sum()`.
- * To find the maximum, see `Math\max()`.
- * To find the minimum, see `Math\min()`.
+ * - To find the sum, see `Math\sum()`.
+ * - To find the maximum, see `Math\max()`.
+ * - To find the minimum, see `Math\min()`.
  */
 function mean(Container<num> $numbers): ?float {
   $count = (float)C\count($numbers);
@@ -99,8 +99,8 @@ function median(Container<num> $numbers): ?float {
  * Returns the smallest element of the given Traversable, or null if the
  * Traversable is empty.
  *
- * For a known number of inputs, see `Math\minva()`.
- * To find the largest number, see `Math\max()`.
+ * - For a known number of inputs, see `Math\minva()`.
+ * - To find the largest number, see `Math\max()`.
  */
 function min<T as num>(
   Traversable<T> $numbers,