hare

[hare] The Hare programming language
git clone https://git.torresjrjr.com/hare.git
Log | Files | Refs | README | LICENSE

hare-doc.5.scd (2134B)


      1 hare-doc(5)
      2 
      3 # NAME
      4 
      5 hare-doc - Hare documentation format
      6 
      7 # DESCRIPTION
      8 
      9 Hare documentation is written in a simple markup language. *haredoc*(1) will
     10 display the documentation literally, without any additional formatting. Other
     11 tools may format Hare documentation into other formats.
     12 
     13 Text may be written normally, broken into several lines to conform to the
     14 80-column limit. To begin a new paragraph, insert an empty line.
     15 
     16 References to other declarations and modules may be written in brackets, like
     17 this: [[os::stdout]]. References to modules should include a trailing :: in the
     18 identifier: [[os::exec::]].
     19 
     20 A bulleted list can be started by opening a line with "-", optionally preceded
     21 by a space. Each line opened like this begins a new list item. To complete the
     22 list, insert an empty line.
     23 
     24 Code samples may be used by starting a line with a single tab, optionally
     25 preceded by a space.
     26 
     27 This markup language is extracted from Hare comments preceding exported symbols
     28 in your source code, and from a file named "README" in your module directory, if
     29 present.
     30 
     31 # EXAMPLE
     32 
     33 ```
     34 // Foos the bars. See also [[foobar]].
     35 //
     36 // If you instead want to bar the foos, use one of the functions in
     37 // [[bar::foo::]].
     38 //
     39 // - First, the bars are obtained.
     40 // - They are then fooed.
     41 // - Finally, the result is returned.
     42 //
     43 //      let x = example();
     44 //      assert(x == 0);
     45 export fn example() int = 0;
     46 ```
     47 
     48 # NOTES
     49 
     50 It's expected that tools which parse documentation for the purpose of converting
     51 it into another format will perform additional processing to decouple the
     52 content from its original textual representation:
     53 
     54 - Line breaks within a paragraph or list item should be ignored.
     55 - Repeated whitespace outside of a code sample should be collapsed.
     56 - Multiple code samples separated by empty lines should be collapsed into one
     57   code sample, so the empty lines are moved into the code sample itself.
     58 
     59 *hare::parse::doc::* in the standard library handles all of this processing for
     60 you.
     61 
     62 Parsers are permitted (and encouraged) to error out on invalid input, such as a
     63 malformed or unterminated [[reference]].
     64 
     65 # SEE ALSO
     66 
     67 *haredoc*(1)