RFC: Support autogenerated documentation for method results, in addition to parameters

[RyanGlScott]

Currently, the DescribedParams class allows for declaring the documentation for the parameters of methods, but not the results. This makes it insufficient for generating the sorts of documentation like what is written here in the handwritten SAW remote API docs.

This is an attempt at augmenting the DescribedParams class to allow documenting result values in addition to parameters. Some of the highlights are:

• The class has now been renamed to DescribedMethod to reflect its more general purpose.
• DescribedMethod now has two type parameters: params (which existed before) and result. There is a params -> result functional dependency since the params type is almost always a custom data type, whereas result can often be off-the-shelf data types like Value and ().
• In addition to the parameterFieldDescription method, there is now a resultFieldDescription method. It has a default implementation of [] in the common case where result is () (i.e., nothing is returned).
• There has been some reorganization of the autogenerated documentation so that there is a more clear separation of the parameters and results.

[pnwamk]

This looks like a great improvement for all the servers!

One minor question -- in the generated docs, there is now for each method a Parameters section and a Return fields section, and I have this nagging feeling that they should match a little more. Would Parameter fields and Return fields be the most sensible similar "more similar" names? (I'm assuming the "fields" suffix is because we're literally talking about JSON object fields, in which case it seems reasonable to me to have it appear as such on both sections).

[RyanGlScott]

One minor question -- in the generated docs, there is now for each method a Parameters section and a Return fields section, and I have this nagging feeling that they should match a little more. Would Parameter fields and Return fields be the most sensible similar "more similar" names? (I'm assuming the "fields" suffix is because we're literally talking about JSON object fields, in which case it seems reasonable to me to have it appear as such on both sections).

Good question. I only chose the name "Return fields" since there was existing precedent for it in the SAW remote API's documentation (see here), so I simply copied it verbatim. But I agree with your desire for consistency, so I've added a commit which changes "Parameters" to "Parameter fields".

On a related note, I'm not entirely wedded to the way argo formats the autogenerated documentation. Currently it just uses subsections for the parameter/return fields, but it might look even nicer to use RST tables like in the SAW remote API's handwritten documentation. However, I don't think argo currently supports decoratively specifying tables like it does other forms of RST, so that would be a larger lift than what this PR implements. I'll open an issue about this point after this lands.

[pnwamk]

On a related note, I'm not entirely wedded to the way argo formats the autogenerated documentation. Currently it just uses subsections for the parameter/return fields, but it might look even nicer to use RST tables like in the SAW remote API's handwritten documentation. However, I don't think argo currently supports decoratively specifying tables like it does other forms of RST, so that would be a larger lift than what this PR implements. I'll open an issue about this point after this lands.

Yes, this is also a great point. The handwritten docs for saw-remote-api are easier to quickly parse and are much more pleasing to the eye than our current auto-formatted docs.

[RyanGlScott]

I've opened #162 to track formatting this information into tables.