Add human-readable meta-data (title, description, examples) to registry entries

[stasm]

A follow-up to #368.

The current draft of the registry spec omits all human-readable descriptions. @aphillips noted in #368 (comment):

I assume this title (and others such as the one on line 24) are meant to be human readable descriptions of the function/input/parameter? If so, it's bad practice to make them an attribute--because they can't easily be localized that way. It's better to make subsidiary elements to contain natural language text. The title fields don't appear to be necessary to the functionality in any case.

[aphillips]

I think a registry without human-readable (natural language) metadata will have a lot of unstructured comments in it.

I support adding fields like title or description to assist in making the registry (and specific implementations of the registry) usable. However, if we add these fields, we should definitely do so in an internationalized way--allowing multiple descriptions in different languages and with language tags (even if the default registry comes with lang="und" or lang="en" only)

[macchiati]

Imo a bad idea from a maintenance point of view. Much better to have localized descriptions in 1 or more separate files.

…

On Sat, Jul 29, 2023, 14:00 Addison Phillips ***@***.***> wrote: I think a registry without human-readable (natural language) metadata will have a lot of unstructured comments in it. I support adding fields like title or description to assist in making the registry (and specific implementations of the registry) usable. However, if we add these fields, we should definitely do so in an internationalized way--allowing multiple descriptions in different languages and with language tags (even if the default registry comes with lang="und" or lang="en" only) — Reply to this email directly, view it on GitHub <#405 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJLEMBT2EKKRQNN6W4MIH3XSV2WBANCNFSM6AAAAAAZ4U5KDQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[mihnita]

+1 to separate files

---

I would also add URLs. Quite useful, and if we don't have something dedicated then people will dump them in <description>

[aphillips]

I didn't specify the exact mechanism, but we should hew to best practices in this space. True documentation should live in documentation space. Machine readable documentation should not overlook what's needed. That is, if we have:

<function>
   <description>This does something useful...</description>

We should do:

<function>
   <description xml:lang="en">This does something useful...</description>

I support providing URLs.

[aphillips]

@eemeli per our slack conversation Monday, see the preceding comments...

[eemeli]

Resolved in #533.