have you heard about this? doccords. a way to implant documentation directly into your hoon app through mostly standard commenting!
there's a great sample file called deco.hoon which should exist inside your urbit right now at base/lib/deco/hoon.
for this guide, we'll crack that open and see if my little bird-brain can make heads or tail-feathers of it.
let's start in a different place than the sample file. head over to dojo to build deco.hoon and search it's comments for doccord documentation.
build the file
=deco -build-file %/lib/deco/hoon
start with
# deco
now
# deco/say-hello
for doccords use # followed by an ace and a path to pull documentation for things like cores and arms.
so what do we see?
with only calling the name of the file we see
> # deco
.deco
^deco
engines for our imaginary hello, world app.
< 5.hgs
8.jnk
15.cxp
...
arms:
+default-jam
bunts $jam
+default-juice
bunts $juice
+say-goodbye
say a really proper goodbye
+say-hello
say hi to someone
+say-minimum
minimal decoration
compiled against:
^deco
structures for our imaginary hello, world generator.
we'll ignore the the odd marks, .deco and ^deco, for now.
but in response we see a description
“engines for our imagniary hello, world app.” which sounds like a core.
then we see oddly familiar number dot hashes, a list of arms, and a second descriptions of a core which also explains that the previous core is “compiled against:” it.
let's take a closer look at the number dot hashes. the < 5.hgs, 8.jnk, 15.cxp ...>. I don't know the official name for this, but it reveals info about your subject.
in this case 5.hgs is saying there are 5 arms in the outermost core of your subject onion. the layer inside of that has 8 arms and inside that 15 arms, and the rest is truncated.
if you want to see the rest of the layers of your subject onion, type . and hit enter in dojo. the final line will show the subject, as seen by dojo. in my case it's
<15.cxp 38.vmz 14.ctx 54.zes 77.xii 236.nqc 51.enr 139.uat 33.rnj 1.pnw %139>`
notice how the outmost layer of this onion is 15.cxp. then it steps further and further down into the irreducible parts of the subject like hoon.hoon, and even more mysterious and delicious inner layers I don't yet understand.
that little tidbit about the subject isn't relevant to doccords. but seeing it here gave me an “ah-ha” moment. so I thought I'd share.
that outermost layer 5.hgs has 5 arms. and what do we see listed under arms:?
arms:
+default-jam
bunts $jam
+default-juice
bunts $juice
+say-goodbye
say a really proper goodbye
+say-hello
say hi to someone
+say-minimum
minimal decoration
yup, 5 arms with nice little descriptions underneath each.
this exapanded my little bird-brain, because I can actually see how subject oriented programming works.
deco.hoon is two cores composed together. the structure core, has 8 arms and it stacks ontop of the deeper and ubiquitous subject onion. then the 5 arm core sits ontop of all of that.
I always heard about “the subject” but this helped me see it. and especially see how “the subject” is dynamic. it changes with every newly composed core. and every file, or series of files, creates their own subject as they build up from the core subject onion.
mmm.
let's double back to what we see when we run
> # deco/say-hello
+say-hello
say hi to someone
txt=@tas -> ""
product:
friendly welcome message
with this we see the description for the arm. then, because the arm is a gate, we see the input to output conversion that occurs. in this case, a @tas gets eaten and a tape gets pooped out.
which we can confirm in the dojo
> (say-hello:deco %douglas)
"hello, douglas"
and at the end we see a description of the product (aka what gets pooped out).
very handy indeed.
one thing I'm uncertain of is how to see the doccord contents of the inner core, the 8 arm core. we know it's there from the subject onion, but from here I wouldn't know how to pull out it's documentation.
but because we can read the file, we can pull the arm descriptions.
> # deco/spot
+spot
* -> [p=@ q=@]
$:
a coordinate
that works nicely. looks like +spot is a mold that makes sure a noun becomes [p=@ q=@].
another thing, here in the dark, are the chapters. +| %molds, +| %mold-builders, and +| %constant are all chapters within this core.
we can pull their info out too
> # deco/mold-builders
|mold-builders
mold builders are functions that build molds from other molds
other languages might call these "type constructors"
or "higher-kinded types".
arms:
+binary-tree
tree mold builder
chapters look pretty similar to what we see from # deco. it too gives a list of arms and a general description of itself.
one more neat thing we don't immediatly see. you can now pull the doccords of any hoon you like.
try
# list
and it might not surprise you now, that you can find it through deco too
# deco/list
that will be helpful.
in order to really learn how to use doccords within your own code, you should study the sample file. however the options available will seem natural.
for example, if you want to make a description for a core or chapter write a comment above
:: molds are functions that normalize nouns.
::
:: arms producing molds are introduced with {+$}. the
:: compiler will copy the arm decoration onto its product
+| %molds
in this case, the “formal” comment is indented by four aces and then it is followed by a paragraph. the paragraph has an empty comment line above it.
you've also seen comments lined up on the right
+$ goof :: a simple tuple mold
$: foo=@ :: something mysterious
bar=@ :: go here for drink
moo=(binary-tree juice) :: cows do this
==
when the comment is on the same line the comment is describing the hoon to the left of it.
> # deco/molds/goof
+goof
a simple tuple mold
neat.
another thing that works, is a formal comment that sits far away from what it is describing. these require labeling with the same face as well as indicating the type of thing.
this description is 15 lines above the mold it describes
:: $jam: some delicious jam
... 15 lines later
+$ jam @tas
in dojo
> # deco/jam
+jam
some delicious jam
* -> @tas
when I say the type of thing, I should probably really say lexical location. here is a list of lexical locations given in deco.hoon.
|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 segmentfrom what I undestand only $foo and +foo are supported right now (summer 2023). and when using these it's important to use them “above an arm in the core to which they are to be attached”.
this will help make sense of the .deco and ^deco from when we ran # deco before.
let's look at something I expected to be able to do
> # deco/molds/goof/moo
Could not find help B
but no answer.
here's the strange new thing that actually gives me access to the description of moo
> ?? moo:*goof:deco
<|cows do this|>
~
?? wutwut is something I've never seen before. my guess is that it's a dojo specific thing.
I have to bunt *goof:deco for a moo to be “created”.
but really cool to see that description.
I never noticed how paths go in the opposite direction of wings. like moo:*goof:deco goes from specific to general. but paths start general. flipping between the two gives me the feeling I get when I go from hoon to javascript and back.
that can't be helped I guess.
like really. I'm too tired to keep going.
there's more to it. putting code in your description requires six aces between the :: and the code. but that seems a bit finacky.
if you use a lexical location, :: $foo and then follow it with a paragraph you have to indent them differently. i.e. if you go with two aces first you have to go with four aces for the paragraph. but if you always use four aces for your formal comment you won't have to remember that.
okay actually done now.
your feathered friend,
nord bird