Feature #19929
Updated by Brett Smith about 1 year ago
Just like every public class and method in the Python SDK should have its own docstring, every public schema, resource type, and method in the API server's discovery document should have a consistent @description@. SDKs in every language can use this to generate documentation.
IMO unless some other requirement overrides, @description@ fields should follow the same "Markdown formatting rules we use for Python docstrings":https://dev.arvados.org/projects/arvados/wiki/Coding_Standards#Python-docstrings, for the same reasons: to provide a presentation that looks good in both plaintext and HTML.
* Make sure all parameters of all methods are advertised. Known missing:
** The @select@ parameter of @get@ methods
* Make sure all parameters of all methods have a description. Known missing:
** @list@ parameters @count@, @distinct@, @filters@, @limit@, @offset@, @order@, @where@
* Make sure all method parameters with default values advertise that default correctly—with a possible exception for parameters that _must_ be cluster-specific like @cluster_id@. Known missing:
** The @select@ attribute of most methods
** @list@ parameters @bypass_federation@, @filters@, @order@, @where@.