ilyakooo0/urbit
1
0
Fork 0
mirror of https://github.com/ilyakooo0/urbit.git synced 2025-01-03 04:40:50 +03:00
Code Issues Packages Projects Releases Wiki Activity

doccords: change :: in lib/deco to :>

Browse Source
This commit is contained in:
drbeefsupreme 2022-07-06 17:30:52 -04:00
parent 862f6cc899
commit 4dd8b4d043
1 changed files with 92 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
pkg/arvo/lib/deco.hoon
View File

@ -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.
:>