Commentary in source code of standard library documentation

[rmariani]

Each entry in the standard library documentation has an accompanying block of its hoon.hoon source. From hoon.hoon it inherited an uneven pattern of code commentary.

For example:

++  gte
  ~/  %gte
  :>    unsigned greater than or equals
  :>
  :>  returns whether {a >= b}.
  :>
  :>  a: left hand operand (todo: name)
  :>  b: right hand operand
  |=  [a=@ b=@]
  :>  greater than or equal to?
  ^-  ?
  !(lth a b)
::

No code commentary can be seen for ++gte in basic arithmetic doc, though. This is typical for all the standard library docs. Maybe that's intentional, to make things bite-sized. Or because some of this commentary is redundant with regard to the explanation that is already given in the library. Or perhaps it's that hoon.hoon has been updated with more commentary since then.

So what should be philosophy of source commentary? My instincts tell me that the obvious approach is to comment the code only where something would benefit from being clarified. However, this would result in standard library documents that take considerably longer to update/write.

Side note: It seems that :> is deprecated. Ted introduced me to a new method of leading commentary that can be seen in the turbo-ford branch.

[rmariani]

would appreciate input from @vvisigoth @joshuareagan @keatondunsford

[cgyarvin]

My input is: still working on the language features required to specify this precisely, but for now use the turbo-ford notation

On Mon, May 14, 2018 at 4:49 PM, rmariani notifications@github.com wrote:

would appreciate input from @vvisigoth https://github.com/vvisigoth @joshuareagan https://github.com/joshuareagan @keatondunsford https://github.com/keatondunsford

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/265#issuecomment-388997947, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAYFqFX0v3v32rICm0bM_S4HNEiq4ks5tyhf1gaJpZM4T-rlG .

[xykj61]

As @belisarius222 hinted at in his earlier comments in urbit/docs#264, in the future, the docs should really auto-generate from the literate documentation in the Arvo source. There's no reason Urbit-flavored markdown and Ford couldn't support this at some date in the future. With that being said, often (almost always), the inline documentation refers to the code that follows it in the next line(s). If this was extracted out of the included source itself into an external paragraph, it might get confusing. I'm fine with the commentary getting included in the source, and then additional commentary can supplement the source in surrounding paragraphs if necessary.

To clarify, the code is in fact more up-to-date than the doc. And as Curtis said, the code and language features are still in progress. Mirroring ford-turbo style is definitely the way to go for now.

[cgyarvin]

Confirm what Keaton says here.

On Mon, May 14, 2018 at 5:16 PM, Keaton Dunsford notifications@github.com wrote:

As @belisarius222 https://github.com/belisarius222 hinted at in his earlier comments in urbit/docs#264 https://github.com/urbit/docs/pull/264, in the future, the docs should really auto-generate from the literate documentation in the Arvo source. There's no reason Urbit-flavored markdown and Ford couldn't support this at some date in the future. With that being said, often (almost always), the inline documentation refers to the code that follows it in the next line(s). If this was extracted out of the included source itself into an external paragraph, it might get confusing. I'm fine with the commentary getting included in the source, and then additional commentary can supplement the source in surrounding paragraphs if necessary.

To clarify, the code is more up-to-date than the doc. And as Curtis said, the code and language features are still in progress. Mirroring ford-turbo style is definitely the way to go for now.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/265#issuecomment-389002401, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAcrT4SsQnum6m-ShuZS3GWkldUSGks5tyh5VgaJpZM4T-rlG .