((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/cock" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "cock" (p "Cock has been deprecated for " (int-link "hahn" "hahn") ".") (toc) (section 3 "Introduction" (p "Cock is a mechanism for documenting Scheme in the source-code itself; similar to " (link "http://www.stack.nl/~dimitri/doxygen/" "Doxygen") ", " (link "http://en.wikipedia.org/wiki/Javadoc" "Javadoc") " or " (link "http://roxygen.org/" "Roxygen") ".") (p "As an example, let's take this naïve Fibonacci:") (highlight scheme "(define (fibonacci n)\n  @(\"Computes the nth [[http://en.wikipedia.org/wiki/Fibonacci_number|Fibonacci]].\"\n    \"This naïve algorithm runs in ''O(2^n)''; using e.g. memoization,\nwe could bring it down to ''O(n)''.\"\n    (n \"The nth number to calculate\")\n    (@to \"integer\")\n    (@example\n     \"Computing the 6th Fibonnaci number (starting from 0)\"\n     (fibonacci 6)))\n  (case n\n    ((0) 0)\n    ((1) 1)\n    (else (+ (fibonacci (- n 1))\n             (fibonacci (- n 2))))))") (p "It produces the following output:") (section 4 (tt "fibonacci") (def (sig (procedure "(fibonacci n) → number" (id fibonacci))) (p "Computes the nth " (link "http://en.wikipedia.org/wiki/Fibonacci_number" "Fibonacci number") ".") (p "This naïve algorithm runs in " (i "O(2^n)") "; using e.g. memoization, we could bring it down to " (i "O(n)") ".") (dl (dt (tt "n")) (dd "The nth number to calculate")) (highlight scheme "(define (fibonacci n)\n  (case n ((0) 0) ((1) 1) (else (+ (fibonacci (- n 1)) (fibonacci (- n 2))))))")) (section 5 "Examples" (p "Computing the 6th Fibonnaci number (starting from 0)") (pre "(fibonacci 6)\n=> 8")))) (section 3 "Syntax" (p "To document definitions, insert a so-called document-expression (\"docexpr\") after the variable (or variable-formals) and before the body of the definition.") (p "The docexpr is an ampersand-prefixed expression containing a description; and optionally a longer description, parameters, return values and examples.") (section 4 "Variables" (p "Variables such as constants and parameters, for example, only require a description:") (highlight scheme "(define k @(\"The Boltzmann constant\") 1.38e-23)") (p "The general form for variables is therefore something like:") (highlight scheme "(define <variable> @(<description> [<longer description>]) <expression>)")) (section 4 "Procedures" (p "Procedures, on the other hand, can provide parameters, return-values and examples; parameters are specified with key-value lists containing the parameter and a description of the parameter; whereas return-values and examples are key-value lists containing the special keys " (tt "@to") " and " (tt "@example") " respectively.") (highlight scheme "(define (add x y)\n  @(\"Adds two numbers.\"\n    (x \"The augend\")\n    (y \"The addend\")\n    (@to \"number\")\n    (@example \"Adding two imprecise binary numbers\"\n              (add #b1# #b1##)))\n  (+ x y))") (p "Notice that " (tt "@example") " takes a description, too; the general form for procedures is therefore something like:") (highlight scheme "(define (<variable> <formals>)\n  @(<description>\n    [<longer description>]\n    [(<formal-0> <formal-description-0>) ...\n     (<formal-n> <formal-description-n>)]\n    [(@to <return-type>)]\n    [(@example <example-description>\n               <example-expression-0> ... <example-expression-n>)]))")) (section 4 "Special tags" (section 5 (tt "@example") (p "The " (tt "@example") " tag is useful for providing examples of procedure-application.") (highlight scheme "(define (quadratic-diophantine z)\n  @(\"Finds a solution to the quadratic Diophantine equation x^2 + y^2 = z^2, given z.\"\n    \"Returns two values, x and y.\"\n    (z \"The known side\")\n    (@to \"number, number\")\n    (@example \"An example from Arithmetica II.VIII\"\n              (quadratic-diophantine 16)))\n  (let* ((m (random (inexact->exact (floor (sqrt z)))))\n         (n (sqrt (- z (expt m 2)))))\n    (let ((x (- (expt m 2) (expt n 2)))\n          (y (* 2 m n)))\n      (values x y))))")) (section 5 (tt "@example-no-eval") (p "The " (tt "@example-no-eval") " tag is also useful for providing examples of procedure-application; the difference is that cock does not attempt to evaluate them when rendering the documentation.") (p (tt "@Example-no-eval") " is useful when the examples are incomplete or pathological.") (highlight scheme "(define (find-fermat-counterexample)\n  @(\"Finds positive integers a, b, c and n > 2 for which a^n + b^n = c^n.\"\n    (@example-no-eval \"Warning: this should never terminate.\"\n                      (find-fermat-counterexample)))\n  ;; The testable range is pretty small.\n  (let ((range 8))\n    (until (let ((a (+ (random range) 1))\n                 (b (+ (random range) 1))\n                 (n (+ (random range) 3)))\n             (integer? (expt (+ (expt a n) (expt b n)) (/ 1 n)))))))")) (section 5 (tt "@internal") (p "The " (tt "@internal") " tag signifies that the documentation for the given expression should be suppressed; it is useful for internal documentation.") (highlight scheme "(define cat-alive?\n  @(\"Qubit representing whether or not our cat is alive\"\n    \"{{Cat-alive?}} is internal so that observers are forced to use\nthe {{observe!}} procedure.\"\n    (@internal))\n  (make-qubit))")) (section 5 (tt "@no-source") (p "The " (tt "@no-source") " tag turns off the source-code listing that accompanies documented expressions.") (highlight scheme "(define (vote! candidate)\n  @(\"[[http://youtu.be/IoWJkrlptNs|Votes]] for your candidate!\"\n    \"This black-box voting procedure is the trade-secret of Biedolb,\nInc.; the source-code has been suppressed.\"\n    (candidate \"The candidate for which to vote\")\n    (@no-source))\n  (register-vote! 'president-mccain))")) (section 5 (tt "@to") (p "The " (tt "@to") " tag is optional and specifies the return value of a procedure; in the absence of " (tt "@to") ", the return value is considered to be " (tt "unspecified") ".") (p "This procedure, for instance, has an " (tt "unspecified") " return type:") (highlight scheme "(define (entangle! register . qs)\n  @(\"Entangles qubits in a register.\"\n    (register \"The register in which to entangle\")\n    (qs \"The qubits to be entangled\"))\n  (for-each (lambda (q) (set-register! q register)) qs))") (p "whereas this one returns a specific type:") (highlight scheme "(define (apply-gate gate . qs)\n  @(\"Applies the quantum-gate to the qubits.\"\n    (gate \"The quantum gate to apply\")\n    (qs \"The qubits on which to apply it\")\n    (@to \"qubit\"))\n  (make-qubit (matrix-multiply (apply quantum-state qs) gate)))"))) (section 4 "Top-level directives" (p "Some of the top-level directives deal with metadata already gleaned from the " (tt ".meta") " file and are therefore redundant; others deal with presentation, and are useful for crafting introductions, &c.") (section 5 (tt "author") (p (tt "Author") " is the author of the egg; it overrides " (tt "(author \"Egg Author\")") " from the " (tt ".meta") " file.") (highlight scheme "@(author \"Diophantus of Alexandria\")")) (section 5 (tt "description") (p (tt "Description") " describes the egg; it overrides " (tt "(synopsis \"Egg synopsis\")") " from the " (tt ".meta") " file.") (highlight scheme "@(description \"To divide a given square number into two squares\")")) (section 5 (tt "egg") (p (tt "Egg") " is the name of the egg; it overrides the filename of the " (tt ".meta") " file (i.e. \"name\" from " (tt "name.meta") ").") (highlight scheme "@(egg \"arithmetica\")")) (section 5 (tt "email") (p (tt "Email") " is the author's email; it overrides " (tt "(email \"author@example.com\")") " from the " (tt ".meta") " file.") (highlight scheme "@(email \"diophantus@alexandria.net\")")) (section 5 (tt "example") (p (tt "Example") " is a stand-alone example, as opposed to the " (tt "@example") " tag that accompanies procedures.") (highlight scheme "@(example \"Riastradh once asked why this does what it does; no one had\na satisfactory answer.\"\n  (let* ((yin ((lambda (y) (newline) y)\n                       (call/cc call/cc)))\n                 (yang ((lambda (y) (write-char #\\*) y)\n                        (call/cc call/cc))))\n            (yin yang)))")) (section 5 (tt "example-no-eval") (p (tt "Example-no-eval") " is a stand-alone, unevaluated example; as opposed to the " (tt "@example-no-eval") " tag that accompanies procedures.") (highlight scheme "@(example-no-eval \"This will never terminate; thanks, Eli!\"\n                  ((lambda (x) (x x)) (lambda (x) (x x))))")) (section 5 (tt "heading") (p (tt "Heading") " designates a section of the documentation right below the level of title.") (highlight scheme "@(heading \"Arithmeticorum Liber II\")")) (section 5 (tt "noop") (p (tt "Noop") " is an artifact required to separate presentation-based directives from source-code that they don't belong to.") (p "For instance:") (highlight scheme "@(heading \"Abstract\")\n@(text \"This is the body of the abstract.\")\n@(noop)\n\n(define phi\n  @(\"The heading and text above do not belong to this variable.\")\n  (/ (+ 1 (sqrt 5)) 2))")) (section 5 (tt "repo") (p (tt "Repo") " overrides " (tt "(repo \"https://example.com/repo.git\")") " from the " (tt ".meta") " file.") (p "(TODO: Implement this.)")) (section 5 (tt "source") (p (tt "Source") " provides a stand-alone source-code listing.") (highlight scheme "@(text \"Through an aggressive heuristic, we've managed to solve the\nhalting problem: let's assume that if it doesn't finish in 1 second,\nit never will.\")\n\n@(source\n  (define (terminate? thunk)\n    (let ((thread (thread-start! (make-thread thunk))))\n      (and (thread-join! thread 1 #f)\n           (thread-terminate! thread)\n           #t))))")) (section 5 (tt "subheading") (p (tt "Subheading") " designates a section of the documentation right below the level of heading.") (highlight scheme "@(subheading \"Quaestio VIII\")")) (section 5 (tt "subsubheading") (p (tt "Subsubheading") " designates a section of the documentation right below the level of subheading.") (highlight scheme "@(subsubheading \"Observatio domini Petri de Fermat\")")) (section 5 (tt "text") (p (tt "Text") " is used for free-form text and can be useful for abstracts and explanatory material.") (highlight scheme "@(text \"I have discovered a truly marvellous proof of this, which this\nmargin is too narrow to contain.\")")) (section 5 (tt "title") (p (tt "Title") " overrides the egg-name as the title of the document.") (highlight scheme "@(title \"Arithmetica\")")) (section 5 (tt "username") (p (tt "Username") " is the username of the author on Chicken's wiki; it overrides " (tt "(user \"chicken-user\")") " from the " (tt ".meta") " file.") (highlight scheme "@(username \"pfermat\")") (p "(TODO: Let's rename this " (tt "user") ".)")))) (section 3 "Complete example" (p "To tie everything together, here's a " (link "https://github.com/klutometis/landauer" "complete example") "; see the " (link "https://wiki.call-cc.org/eggref/4/landauer" "resulting documentation") ".") (section 4 ("The " (tt ".meta") " file") (p "Cock reads the metadata from the " (tt ".meta") " file such as: " (tt "synopsis") ", " (tt "author") ", " (tt "email") ", " (tt "user") ", " (tt "repo") ", " (tt "depends") ".") (highlight scheme "((synopsis \"Use the Landauer limit to calculate my program's entropy.\")\n (author \"Peter Danenberg\")\n (email \"pcd@roxygen.org\")\n (user \"klutometis\")\n (repo \"https://github.com/klutometis/landauer\")\n (category math)\n (license \"BSD\")\n (depends cock)\n (test-depends test)\n (foreign-depends))")) (section 4 "The module file" (p "The module file is a suitable place for putting introductory material about the egg; such as background information, abstract, &c.") (p "It is also suitable for a high-level overview of what the module does.") (highlight scheme "@(heading \"Landauer's principle\")\n\n@(text \"[[http://en.wikipedia.org/wiki/Landauer%27s_principle|Landauer's\nprinciple]] states that every irreversible operation produces\nentropy; erasing one bit, for instance, generates at least ''kT'' ln\n2 J of heat.\")\n\n@(text \"We can use Landauer's principle to calculate a lower-bound on\nthe energy released by our program, given some number of\nbit-operations.\")\n\n@(heading \"Documentation\")\n@(noop)\n\n(module landauer\n  @(\"The Landauer module contains contains some constants, parameters\nand procedures for calculating a lower-bound on the heat-dissipation\nof programs.\")\n  (heat\n   k\n   room-temperature)\n  (import chicken scheme)\n  (include \"landauer-core.scm\"))")) (section 4 "The source file" (p "The source file contains the documentation of individual constants, parameters, records, procedures.") (highlight scheme "(define k @(\"The Boltzmann constant\") 1.38e-23)\n\n(define room-temperature @(\"Room temperature in K\")\n  (make-parameter 298.15))\n\n(define (heat operations)\n  @(\"Calculate a lower-bound on the heat dissipated by some number\nof irreversible bit-operations.\"\n    \"Room-temperature is governed by the [[#room-temperature]]\nparameter.\"\n    (operations \"The number of irreversible bit-operations\")\n    (@to \"number\"))\n  (* operations k (room-temperature) (log 2)))")) (section 4 ("The " (tt ".setup") " file") (p "The " (tt ".setup") " file does two things:") (ol (li "compiles each extension with " (tt "-X cock") "; and") (li "generates documention.")) (p "Extensions should be compiled with " (tt "-X cock") "; this strips the documentation from the source before compilation so that the compiler is not confused.") (p "The " (tt "cock") " binary from " (int-link "cock-utils") " generates the actual documentation; the " (tt "cock") " egg provides a convenience macro " (tt "run-cock") " so that installation does not fail for users who haven't installed " (tt "cock-utils") ".") (p "There is a soft-dependency on the otherwise dependency-heavy egg " (tt "cock-utils") ": users don't have to have it unless they want to generate docs themselves, for some reason.") (highlight scheme "(use cock setup-helper-mod)\n\n(setup-shared-extension-module\n 'landauer\n (extension-version \"0.0.1\")\n compile-options: '(-X cock))\n\n(run-cock -o landauer.wiki landauer.scm landauer-core.scm)"))) (section 3 "Limitations" (ul (li "The repository-awareness is Git-specific.") (li "The version-awareness is Github-specific.")))))