diff --git a/pkg/arvo/lib/deco.hoon b/pkg/arvo/lib/deco.hoon index bed81f2d9..7c4d6be64 100644 --- a/pkg/arvo/lib/deco.hoon +++ b/pkg/arvo/lib/deco.hoon @@ -1,95 +1,95 @@ -:: Hoon doccords sample -:: -:: this is a sample file designed to explain syntax and conventions -:: for doccords -:: -:: all lines must be under 80 characters. no blank lines. -:: any line longer than 60 characters is probably too long. -:: uppercase or non-ascii letters are strongly discouraged. -:: -:: informal comments (lines with {::}) should be used only for -:: meta-discussion *about* the code. -:: -:: whenever possible, use formal decorations. {:>} decorates -:: the next expression; {:<} decorates the previous one. -:: -:: there are two places to put decorations: in line with the -:: code, and on the right margin. -:: -:: the file below is a well-commented library, built around -:: a typical two-core structure. the cores are labeled {%arch} -:: (structures) and {%work} (productions). -:: -:: this code is written to display the variety of formatting -:: options the parser allows. a specific convention should pick -:: one of these styles and stick to it. -:: -:: there are three ways to mark the beginning of a formal comment: -:: 1: {:: $foo:} -:: 2: {:: +bar:} -:: 3: {:: } -:: -:: style 1 is for single-line comments at a given lexical location -:: (see below), which may be written above any arm in a core and -:: the parser will move the comment to the specified arm. -:: -:: style 2 is much like style 1, but may be followed by a series -:: of paragraphs: -:: {::} -:: {:: more text} -:: {:: even more text} -:: {::} -:: {:: |=(code=hoon !!)} -:: -:: a paragraph is a series of lines, not indented for text, -:: but indented by four extra spaces, {:: }, for code. -:: -:: style 3 is used to annotate the hoon or spec that immediately follows -:: the comment. this may be either a single line comment as in style 1, -:: or multi-line comment as in style 2. -:: -:: the $foo and +bar above are examples of *lexical locations* for -:: style and batch-commenting purposes. this tells the parser to attempt -:: to attach the comment to the specified location. these locations -:: may be written as follows: -:: - `|foo` means a chapter -:: - `%foo` means a constant -:: - `.foo` means a face -:: - `+foo` means an arm -:: - `$foo` means a spec -:: - `^foo` means a core -:: - `_foo` means a door -:: - `=foo` means a gate -:: - `/foo` means a file path segment -:: -:: thus /lib/foo^widget|initial=open means the =open gate in the |initial -:: chapter of the ^widget core in the /foo library -:: -:: at present, doccords does not support lexical locations in full. -:: only single-element locations of the form `$foo` and `+foo` are supported, -:: and must be written above an arm in the core to which they are to be -:: attached. you may still write doccords for these locations, and they -:: will be parsed, but are thrown away before they make it to the compiler. -:: -:: a postfix formal comment will either attach to hoon or spec on the -:: current line, or the arm name if there is no hoon or spec on the -:: line -:: -:: |% and |@ cores can be given @tas names with e.g. `|% %foo`. for -:: now, the only purpose of this is to make cores not built by arms -:: legible to doccords. in order to name any other core type, you will -:: need to desugar it for now. -:: -:: to inspect doccords in this file from dojo, try the following: -:: -:: > =deco -build-file %/lib/deco/hoon -:: > # deco -:: > # deco/arch -:: > # deco/arch/molds -:: > # deco/arch/molds/goof -:: -:: > ?? *goof:deco -:: +:> Hoon doccords sample +:> +:> this is a sample file designed to explain syntax and conventions +:> for doccords +:> +:> all lines must be under 80 characters. no blank lines. +:> any line longer than 60 characters is probably too long. +:> uppercase or non-ascii letters are strongly discouraged. +:> +:> informal comments (lines with {:>}) should be used only for +:> meta-discussion *about* the code. +:> +:> whenever possible, use formal decorations. {:>} decorates +:> the next expression; {:<} decorates the previous one. +:> +:> there are two places to put decorations: in line with the +:> code, and on the right margin. +:> +:> the file below is a well-commented library, built around +:> a typical two-core structure. the cores are labeled {%arch} +:> (structures) and {%work} (productions). +:> +:> this code is written to display the variety of formatting +:> options the parser allows. a specific convention should pick +:> one of these styles and stick to it. +:> +:> there are three ways to mark the beginning of a formal comment: +:> 1- {:> $foo:} +:> 2- {:> +bar:} +:> 3- {:> } +:> +:> style 1 is for single-line comments at a given lexical location +:> (see below), which may be written above any arm in a core and +:> the parser will move the comment to the specified arm. +:> +:> style 2 is much like style 1, but may be followed by a series +:> of paragraphs: +:> {:>} +:> {:> more text} +:> {:> even more text} +:> {:>} +:> {:> |=(code=hoon !!)} +:> +:> a paragraph is a series of lines, not indented for text, +:> but indented by four extra spaces, {:> }, for code. +:> +:> style 3 is used to annotate the hoon or spec that immediately follows +:> the comment. this may be either a single line comment as in style 1, +:> or multi-line comment as in style 2. +:> +:> the $foo and +bar above are examples of *lexical locations* for +:> style and batch-commenting purposes. this tells the parser to attempt +:> to attach the comment to the specified location. these locations +:> may be written as follows: +:> - `|foo` means a chapter +:> - `%foo` means a constant +:> - `.foo` means a face +:> - `+foo` means an arm +:> - `$foo` means a spec +:> - `^foo` means a core +:> - `_foo` means a door +:> - `=foo` means a gate +:> - `/foo` means a file path segment +:> +:> thus /lib/foo^widget|initial=open means the =open gate in the |initial +:> chapter of the ^widget core in the /foo library +:> +:> at present, doccords does not support lexical locations in full. +:> only single-element locations of the form `$foo` and `+foo` are supported, +:> and must be written above an arm in the core to which they are to be +:> attached. you may still write doccords for these locations, and they +:> will be parsed, but are thrown away before they make it to the compiler. +:> +:> a postfix formal comment will either attach to hoon or spec on the +:> current line, or the arm name if there is no hoon or spec on the +:> line +:> +:> |% and |@ cores can be given @tas names with e.g. `|% %foo`. for +:> now, the only purpose of this is to make cores not built by arms +:> legible to doccords. in order to name any other core type, you will +:> need to desugar it for now. +:> +:> to inspect doccords in this file from dojo, try the following: +:> +:> > =deco -build-file %/lib/deco/hoon +:> > # deco +:> > # deco/arch +:> > # deco/arch/molds +:> > # deco/arch/molds/goof +:> +:> > ?? *goof:deco +:> => :: :> structures for our imaginary hello, world generator. :>