#ask How should we improve Motoko?

Developers
60

Idk if that is the accepted term, but it’s the equivalent of Javadoc.

Originally I learned about it while looking through the invoice canister code: examples/main.mo at kyle/invoice-canister-cleanup · dfinity/examples · GitHub

  // #region get_account_identifier
  /*
    * Get Caller Identifier
    * Allows a caller to the accountIdentifier for a given principal
    * for a specific token.
    */
  public query func get_account_identifier(args : T.GetAccountIdentifierArgs) : async T.GetAccountIdentifierResult {

It will make it so hovering over these fields will show a tooltip that looks like (similar method but with additional formatting used):

motokodoc_example
motokodoc_example1011×366 76.4 KB

I found it very useful when first working with the code, and as not as known as Motoko is every bit helps. To add such a comment, start with a /** and end with a */ where the ending */ must be directly above the field declaration (no vertical line spaces). In the snippet above the opening double asterisk can be separated, but I found that the beginning * of each line of comment will also appear in the tooltip.

Syntax I know of so far:

  • the Markdown linking syntax works “[“desc”]”(url)
  • trigger a new line with a \ as the very last character of the current line (no additional white space)
  • terminating a line with double white space will also trigger a new line
  • Double asterisk for bold
  • Single asterisk or underscore for italic
  • code enclosed as back tick marks `
  • The @ sign did something once but I don’t remember what specifically triggered it

If the Motokodoc is one line, I personally like to use:
/**** <One Line Comment Title Text> ***/
to emphasis it as a header.

I’ve been using 80 character spaces before making a new line (since the tool tip won’t autowrap), but maybe the modern max-width convention is 120 chars?

One thing to note is that the \ new line character isn’t escaped when moc doc is used (at least for html output) which is another task to do.

Finally I mentioned that if it would be possible it might be useful to link one field’s Motokodoc into another, so for instance “non-trivial” Result.Result types could automatically show their Success and Error types if (also defined) and linked. Or equally useful would be a way to import the corresponding did field’s comments, since that’s supposed to be the source of truth about a canister for external callers, and much of the info would likely be the same.

2 Likes