hoon, dojo: initial doccords release #5873
Conversation
there's a stub for +* but its not working yet
this populates the $what in $tome
Too often when dealing with big types the compiler traces and other such outputs become hard to read. Wrapping a type as $+(shorthand big-type) will now print #shorthand in place of the type.
This changes the parser for +tall so that it looks before and after a hoon for doccords, and then extracts a label for %brcn if it exists. +wrap will be used to annotating most hoons, but this commit only covers %brcn
This reverts commit 0dc3498.
this changes the parser to take any bar runes surrounded by formal comments and wraps them with %note tags containing those comments
wraps the skin in tisface with a %help skin
wraps them in %note hoons
initial commit for library for finding and printing doccords. has some basic functionality for looking through a type and finding the docs within it and printing them, but is mostly unfinished
doesn't totally work yet
if the product had its own docs, it wouldn't also get the docs for a the default arm produced by the core. this fixes that. also misc style fixes
also adds another mule to a play:ut call to avoid another crash that i'm not sure yet why it is happening
adds the ability to find cores and chapters and produce an item from them
docs written above an arm are now distinguishable in the AST from docs written above the product of the arm, by tagging docs written above the arm with a %funk link
rewrites select-arm-docs so that it checks for nested hint types and sees if the outermost help hint has a %funk link with the name of the arm in order to tell that its an arm-doc
stupid loobeans tripping me up
I didn't know what I was doing before, I think this is the right way to wrap tisfas with a %note hoon.
before this, it was grabbing the initial arm-doc from the AST rather than the type. now %arm items have all 3 types of docs available. the interface has been degraded somewhat though, as %arm items no longer have a single docs field. more refactoring will be needed to figure out the best way to do this.
|
The doccords don't show up using the old The fix in https://github.com/urbit/urbit/pull/5873/files#diff-94e19e683e69204abd61d7b5991a01c1db936a982c17b46f8b3d3825497b6d9fR8426-R8432 definitely has some unintended side-effects. If I run you end up with So we're getting identical |
|
The additional |
|
I found something that works for the It also does not have the duplicate
My main concern is with the effect |
everything appears to work fine without them and I don't think it is any less unclear what this gate is doing.
notes aren't just for doccords, of course
all this did was set .nut. while it could be used with doccords, it is currently unused, and none of the other values in the sample of _ax are set this way (bug, def, cox, hay, dom). i experimented a little bit with trying to make use of this but it made things overall more unreadable, and it wouldn't make sense to do it without doing the same for other values of the sample. im guessing this is just an old style.
|
I'm currently looking around for Based on @joemfb 's comment here #5939 (review) I'm guessing that since doccords breaks some jet signatures, it also needs to be a Kelvin release? In which case #6064 should be included as well. |
no idea how this ended up happening, but apparently it was my fault.
anytime a gate prints with a complicated sample or product type it is frequently extremely long. 3 is probably too low of a cutoff number, but ideally a future version will have verbosity settings that will help control this.
|* foo bar is sugar for =+ foo |@ ++ $ bar --, and newbies find the old style confusing. this switches out the |@ pattern for the |* one, at least in layer <=4. the only ones remaining are +toad, +rune, and +runo, which are already tweaked in #5873 so we omit them here.
making hoon.hoon more legible to doccords. also moving some things around that seemed to be in the wrong place
|
Friendly poke to @Fang- about reviewing this. Since @joemfb is out for at least a couple weeks I think its all on you unless you call in backup. I am feeling pretty confident with the |
See #6052. This is completely different from the +* used at the top of doors, and has almost entirely been replaced by |$. The exception is the use of the `%made` spec, not present in `|$`. I do not see an obvious way to change `|$` to use `%made` since this `+*` parser uses the name of the arm in the `%made` structure, unless we change the AST of |$.
This reverts commit e306d32.
|
I believe this is ready to go. I made the following changes:
|
This is a draft since its still a WIP, so there's some code that is obviously sloppy and can be improved, but major features are all working and all tests are passing. A couple minor features still have work to be done.
Short story: you can now wrap an arbitrary
hoonwith%notehooncontaining doccords. You can wrap an arbitrary spec with a%dictspec, containing doccords. Both end up compiled as%hinttypes.Surfacing doccords for arbitrary hoons isn't currently implemented in the printing library, but you can print doccords for cores, chapters, faces, arms, arm products, default arm of a core built by an arm, and molds using
# arm/chapter/core/face, and output values of molds using?? *fooin dojo.OTA is blocked by #5849 which 172af42 is a suggested patch for. I had tried cherry picking this commit, but a fresh fake ship wouldn't compile with it, so I'm probably missing other things from that branch for it to work just yet and so haven't tested the fix with this feature branch. The band-aid in #5849 still works if you'd like to test this out in the meantime.
Examples of doccords syntax can be found in
/lib/dprint.hoon,/lib/deco.hoon/and/tests/lib/dprint.hoon. There's a lot of room for change here - I'll work on an exhaustive list of syntax changes and update this PR soon. The biggest difference is that I plan to replace:<and:>with::with some strict rules on what::comments should be parsed as formal comments. This might end up being pretty difficult.All planned features for the first release are essentially complete (#5768 #5769 #5770 #5771 #5773 #5774 #5775 #5776 #5777 #5778 #5779 #5780 #5781 #5782 #5783 #5784 #5785 #5838) - what's mostly left is arguing over syntax and making the code cleaner.
Some example usage of printing library (output is colorized in dojo - that section of the printing lib is still rough, it needs another look)
Doccords from output value of a mold: