convert the manually-written docpages into doccomments and DocC curations

Author: tayloraswift

.gitignore

@@ -1,4 +1,5 @@
 /.build
+/.build.ssgc
 /.vscode
 /Packages
 .swiftpm

Sources/Noise/cell.swift

@@ -166,6 +166,18 @@ extension _CellNoise2D
     }
 }
 
+/// A type of two-dimensional cellular noise (sometimes called
+/// [Worley noise](https://en.wikipedia.org/wiki/Worley_noise), or Voronoi noise), suitable for
+/// texturing two-dimensional planes.
+///
+/// ![preview](png/banner_cell2d.png)
+///
+/// Unlike many other cell noise implementations, *Noise*’s implementation samples all relevant
+/// generating-points, preventing artifacts or discontinuities from ever appearing in the noise.
+/// Accordingly, *Noise*’s implementation is heavily optimized to prevent the additional edge
+/// cases from impacting the performance of the cell noise.
+///
+/// Cell noise has a three-dimensional version, ``CellNoise3D``.
 public
 struct CellNoise2D:_CellNoise2D, HashedNoise
 {
@@ -180,6 +192,14 @@ struct CellNoise2D:_CellNoise2D, HashedNoise
         self.permutation_table = permutation_table
     }
 
+    /// Creates an instance with the given `amplitude`, `frequency`, and random `seed` values.
+    /// Creating an instance generates a new pseudo-random permutation table for that instance,
+    /// and a new instance does not need to be regenerated to sample the same procedural noise
+    /// field.
+    ///
+    /// The given amplitude is adjusted internally to produce output *exactly* within the range
+    /// of `0 ... amplitude`. However, in practice the cell noise rarely reaches the maximum
+    /// threshold, as it is often useful to inflate the amplitude to get the desired appearance.
     public
     init(amplitude:Double, frequency:Double, seed:Int = 0)
     {
@@ -188,25 +208,34 @@ struct CellNoise2D:_CellNoise2D, HashedNoise
         self.permutation_table = PermutationTable(seed: seed)
     }
 
+    /// Returns the index numbers of the closest feature point to the given coordinate, and the
+    /// squared distance from the given coordinate to the feature point. These index numbers can
+    /// be fed to a color hashing function to produce a
+    /// [Voronoi diagram](https://en.wikipedia.org/wiki/Voronoi_diagram).
     public
     func closest_point(_ x:Double, _ y:Double) -> (point:(Int, Int), r2:Double)
     {
         return self._closest_point(x, y)
     }
 
+    /// Evaluates the cell noise field at the given coordinates.
     public
     func evaluate(_ x:Double, _ y:Double) -> Double
     {
         let (_, r2):((Int, Int), Double) = self.closest_point(x, y)
         return self.amplitude * r2
     }
 
+    /// Evaluates the cell noise field at the given coordinates. The third coordinate is
+    /// ignored.
     public
     func evaluate(_ x:Double, _ y:Double, _:Double) -> Double
     {
         return self.evaluate(x, y)
     }
 
+    /// Evaluates the cell noise field at the given coordinates. The third and fourth
+    /// coordinates are ignored.
     public
     func evaluate(_ x:Double, _ y:Double, _:Double, _:Double) -> Double
     {
@@ -518,6 +547,26 @@ extension _CellNoise3D
     }
 }
 
+/// A type of three-dimensional cellular noise (sometimes called
+/// [Worley noise](https://en.wikipedia.org/wiki/Worley_noise), or Voronoi noise), suitable for
+/// texturing arbitrary three-dimensional objects.
+///
+/// ![preview](png/banner_cell3d.png)
+///
+/// Unlike many other cell noise implementations, *Noise*’s implementation samples all relevant
+/// generating-points, preventing artifacts or discontinuities from ever appearing in the noise.
+/// Accordingly, *Noise*’s implementation is heavily optimized to prevent the additional edge
+/// cases from impacting the performance of the cell noise.
+///
+/// Three dimensional cell noise is approximately three to four times slower than its
+/// [two-dimensional version](doc:CellNoise2D), but has a vastly superior visual appearance,
+/// even when sampled in two dimensions.
+///
+/// `CellNoise3D` is analogous to
+/// [Blender Voronoi noise](https://docs.blender.org/manual/en/dev/render/cycles/nodes/types/textures/voronoi.html),
+/// with the *Distance Squared* metric. The *Scale* of Blender Voronoi noise is identical to the
+/// ``frequency`` of `CellNoise3D`; its range is approximately `0 ... 10/3` in `CellNoise3D`
+/// units.
 public
 struct CellNoise3D:_CellNoise3D, HashedNoise
 {
@@ -532,6 +581,14 @@ struct CellNoise3D:_CellNoise3D, HashedNoise
         self.permutation_table = permutation_table
     }
 
+    /// Creates an instance with the given `amplitude`, `frequency`, and random `seed` values.
+    /// Creating an instance generates a new pseudo-random permutation table for that instance,
+    /// and a new instance does not need to be regenerated to sample the same procedural noise
+    /// field.
+    ///
+    /// The given amplitude is adjusted internally to produce output *exactly* within the range
+    /// of `0 ... amplitude`. However, in practice the cell noise rarely reaches the maximum
+    /// threshold, as it is often useful to inflate the amplitude to get the desired appearance.
     public
     init(amplitude:Double, frequency:Double, seed:Int = 0)
     {
@@ -540,25 +597,34 @@ struct CellNoise3D:_CellNoise3D, HashedNoise
         self.permutation_table = PermutationTable(seed: seed)
     }
 
+    /// Returns the index numbers of the closest feature point to the given coordinate, and the
+    /// squared distance from the given coordinate to the feature point. These index numbers can
+    /// be fed to a color hashing function to produce a
+    /// [Voronoi diagram](https://en.wikipedia.org/wiki/Voronoi_diagram).
     public
     func closest_point(_ x:Double, _ y:Double, _ z:Double) -> (point:(Int, Int, Int), r2:Double)
     {
         return self._closest_point(x, y, z)
     }
 
+    /// Evaluates the cell noise field at the given `x, y` coordinates, supplying `0` for the
+    /// missing `z` coordinate.
     public
     func evaluate(_ x:Double, _ y:Double) -> Double
     {
         return self.evaluate(x, y, 0)
     }
 
+    /// Evaluates the cell noise field at the given coordinates.
     public
     func evaluate(_ x:Double, _ y:Double, _ z:Double) -> Double
     {
         let (_, r2):((Int, Int, Int), Double) = self.closest_point(x, y, z)
         return self.amplitude * r2
     }
 
+    /// Evaluates the cell noise field at the given coordinates. The fourth coordinate is
+    /// ignored.
     public
     func evaluate(_ x:Double, _ y:Double, _ z:Double, _:Double) -> Double
     {

Sources/Noise/compounds.swift

@@ -1,3 +1,7 @@
+/// A generic [fractal brownian motion](https://thebookofshaders.com/13/) noise generator,
+/// capable of overlaying multiple instances of procedural ``Noise`` at increasing frequencies.
+///
+/// ![preview](png/banner_FBM.png)
 public
 struct FBM<Source>:Noise where Source:Noise
 {
@@ -34,6 +38,12 @@ struct FBM<Source>:Noise where Source:Noise
         self.generators = []
     }
 
+    /// Creates an instance with the given number of `octaves` of noise. The given `amplitude`
+    /// is the amplitude of the first octave of noise, and is multiplied by `persistence` for
+    /// each successive octave. The given `frequency` is the frequency of the first octave of
+    /// noise, and is multiplied by the `lacunarity` for each successive octave. The `seed`
+    /// value is passed through to the first octave of noise, and is incremented for each
+    /// successive octave.
     @available(*, unavailable, message: "use init(_:octaves:persistence:lacunarity:) instead")
     public
     init(amplitude:Double, frequency:Double, octaves:Int, persistence:Double = 0.75, lacunarity:Double = 2, seed:Int = 0)

Sources/Noise/disk.swift

@@ -1,3 +1,16 @@
+/// A point sampler capable of producing uniform and roughly-evenly spaced pseudo-random point
+/// distributions in the plane. Disk sampling is sometimes referred to as
+/// [Poisson sampling](https://en.wikipedia.org/wiki/Supersampling#Poisson_disc).
+///
+/// ![preview](png/banner_disk2d.png)
+///
+/// Disk samples are not a noise field — its generation is inherently sequential, as opposed to
+/// most procedural noise fields which are embarrassingly parallel. Thus, disk samples have no
+/// concept of *evaluation*; the entire sample set must be generated as a whole.
+///
+/// Disk samples have an internal state, which is advanced every time the point generator runs.
+/// In many ways, disk samples have more in common with pseudo-random number generators than
+/// they do with procedural noise fields.
 public
 struct DiskSampler2D
 {
@@ -17,6 +30,9 @@ struct DiskSampler2D
     private static
     let candidate_table_bitmask:Int = 0b1111111111 // 1023
 
+    /// Creates an instance with the given fixed random `seed`. This process calculates a random
+    /// table used internally in the sample generation step. The same instance can be reused to
+    /// generate multiple, different point distributions.
     public
     init(seed:Int = 0)
     {
@@ -46,6 +62,13 @@ struct DiskSampler2D
         self.candidate_ring = candidate_ring
     }
 
+    /// Generates a set of sample points that are spaced no less than `radius` apart over a
+    /// region sized `width` by `height` . Up to `k` candidate points will be used to generate
+    /// each sample point; higher values of `k` yield more compact point distributions, but take
+    /// longer to run. The `seed` point specifies the first point that is added to the
+    /// distribution, and influences where subsequent sample points are added. This `seed` is
+    /// orthogonal to the `seed` supplied in the initializer. If `seed` is left `nil`, the seed
+    /// point is placed at the center of the region.
     public mutating
     func generate(radius:Double, width:Int, height:Int, k:Int = 32, seed:(Double, Double)? = nil) -> [(Double, Double)]
     {

Sources/Noise/docs.docc/README.md

@@ -1,43 +1,30 @@
-# ``Noise``
+# ``/Noise``
 
 Generate and combine commonly used procedural noise patterns and distributions.
 
-*This wiki documents features present in* [Noise *1.0.0*](https://github.com/tayloraswift/noise/releases/tag/1.0.0). *Many new features are currently being added to* [`master`](https://github.com/tayloraswift/noise/tree/master) *for* Noise *2.0.0, and several types and methods will be deprecated or removed for 2.0.0, including* [`SimplexNoise2D`](struct-SimplexNoise2D.md).
-***
-
-## Symbols
+## Topics
 
 ### Protocols
 
-#### `protocol` [`Noise`](protocol-Noise.md)
-> A procedural noise generator.
-
-### Structures
-
-#### `struct` [`SimplexNoise2D`](struct-SimplexNoise2D.md)
-> A type of two-dimensional gradient noise (sometimes called [Perlin noise](https://en.wikipedia.org/wiki/Perlin_noise)), suitable for texturing two-dimensional planes. Simplex noise is supported in the library mainly because it has historical significance; it has since been superseded by the less popular, but more powerful and more efficient super-simplex noise.
-
-#### `struct` [`SuperSimplexNoise2D`](struct-SuperSimplexNoise2D.md)
-> A type of two-dimensional gradient noise (sometimes called [Perlin noise](https://en.wikipedia.org/wiki/Perlin_noise)), suitable for texturing two-dimensional planes. Super-simplex noise is an improved version of simplex noise which runs faster and scales better to higher dimensions.
+-   ``Noise``
 
+### Noise generators
 
-#### `struct` [`SuperSimplexNoise3D`](struct-SuperSimplexNoise3D.md)
-> A type of three-dimensional gradient noise (sometimes called [Perlin noise](https://en.wikipedia.org/wiki/Perlin_noise)), suitable for texturing arbitrary three-dimensional objects.
+-   ``SimplexNoise2D``
+-   ``GradientNoise2D``
+-   ``GradientNoise3D``
+-   ``CellNoise2D``
+-   ``CellNoise3D``
 
-#### `struct` [`CellNoise2D`](struct-CellNoise2D.md)
-> A type of two-dimensional cellular noise (sometimes called [Worley noise](https://en.wikipedia.org/wiki/Worley_noise), or Voronoi noise), suitable for texturing two-dimensional planes.
+### Noise composition
 
-#### `struct` [`CellNoise3D`](struct-CellNoise3D.md)
-> A type of three-dimensional cellular noise (sometimes called [Worley noise](https://en.wikipedia.org/wiki/Worley_noise), or Voronoi noise), suitable for texturing arbitrary three-dimensional objects.
+-   ``FBM``
 
-#### `struct` [`DiskSampler2D`](struct-DiskSampler2D.md)
-> A point sampler capable of producing uniform and roughly-evenly spaced pseudo-random point distributions in the plane. Disk sampling is sometimes referred to as [Poisson sampling](https://en.wikipedia.org/wiki/Supersampling#Poisson_disc).
+### Pattern generators
 
-#### `struct` [`FBM`](struct-FBM.md)
-> A generic [fractal brownian motion](https://thebookofshaders.com/13/) noise generator, capable of overlaying multiple instances of procedural [noise](protocol-Noise.md) at increasing frequencies.
+-   ``DiskSampler2D``
 
-#### `struct` [`PermutationTable`](struct-PermutationTable.md)
-> An 8-bit permutation table useful for generating pseudo-random hash values.
+### Psuedo-random number generators
 
-#### `struct` [`RandomXorshift`](struct-RandomXorshift.md)
-> A cryptographically unsecure 128-bit [Xorshift](https://en.wikipedia.org/wiki/Xorshift) pseudo-random number generator.
+-   ``PermutationTable``
+-   ``RandomXorshift``