#1821·penrose

feat: Domain-defined Doc Strings

Author: KyleleeSeaCreated Jul 3, 2024Updated Jul 8, 2024
Labelssystem:domainsystem:language

Is your feature request related to a problem? Please describe. (From conversation with @joshsunshine) A vision of Penrose is for the examples to be extensible so users can use the components in substance to create their own diagrams without having to create their own components. However, it's often not clear how example programs mean for the domain objects to be used. An example: Screenshot 2024-07-03 at 1 38 48 PM

A user would have to comb through the style program and experiment to understand how each of these objects is meant to be used.

With the addition of autocomplete info boxes and hover tooltips we now have better in-editor documentation for built-in functions. We may imagine these features being utilized to show users what each domain defined object means while they're editing in substance.

We have some examples where this documentation exists in domain, but it would be nice if this showed up while the user is writing in substance (in autocomplete info box) so they don't need to scroll back and forth.

Screenshot 2024-07-03 at 1 23 32 PM

Describe the solution you'd like This could be solved one of two ways: A) Adding a Domain Language Feature For example, adding a domain keyword like: Document([type/predicate/function/constructor name], documentation string)

B) Creating a Domain Convention For example, the first comment above a declaration will be included as documentation string.

Note: I don't think this is preferable. This may be annoying to implement since the parser currently skips comments, we'd have to no longer skip comments if we wish to get the comments via traversing the parse tree rather than using regex. Additionally, a user uninformed of this might include comments that they don't expect to be documentation strings. There are also cases where a user may have a comment above a declaration and it simply makes no sense for it to be documentation (like commenting out code).