Feature #19929
open
Improve documentation in the discovery document
Added by Brett Smith over 1 year ago.
Updated about 1 month ago.
Description
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, 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
.
Don't bother with anything deprecated and/or do this after the "declutter the API story".
- Related to Support #18799: Strategy to generate Python SDK docstrings based on API docs added
Estimating one story point based on:
$ git grep -c description: services/api/app/controllers/
services/api/app/controllers/application_controller.rb:8
services/api/app/controllers/arvados/v1/collections_controller.rb:4
services/api/app/controllers/arvados/v1/container_requests_controller.rb:2
services/api/app/controllers/arvados/v1/groups_controller.rb:7
services/api/app/controllers/arvados/v1/nodes_controller.rb:2
services/api/app/controllers/arvados/v1/schema_controller.rb:31
Point being, most of the work is documenting the common methods once in schema_controller
, there aren't tons of exceptions and additions beyond that.
- Release deleted (
60)
- Target version set to To be scheduled
I am proposing we do this as part of improving our documentation generally. It's been groomed. We don't have to take this approach, but I would like to at least discuss it and not postpone it automatically.
- Related to Bug #3817: [API] Discovery document schema does not include generated fields like job dependencies added
- Description updated (diff)
- Target version changed from To be scheduled to Development 2023-05-10 sprint
- Assigned To set to Brett Smith
- Target version changed from Development 2023-05-10 sprint to Development 2023-05-24 sprint
- Target version changed from Development 2023-05-24 sprint to Development 2023-06-07
- Target version changed from Development 2023-06-07 to To be scheduled
- Target version changed from To be scheduled to Development 2023-11-29 sprint
- Description updated (diff)
- Target version changed from Development 2023-11-29 sprint to Development 2024-01-03 sprint
- Target version changed from Development 2024-01-03 sprint to Development 2024-01-17 sprint
- Category changed from Documentation to API
- Tracker changed from Bug to Support
- Tracker changed from Support to Idea
- Target version changed from Development 2024-01-17 sprint to Development 2024-01-31 sprint
- Target version changed from Development 2024-01-31 sprint to Development 2024-02-14 sprint
- Target version changed from Development 2024-02-14 sprint to Development 2024-02-28 sprint
- Target version changed from Development 2024-02-28 sprint to Development 2024-03-13 sprint
- Target version changed from Development 2024-03-13 sprint to Development 2024-03-27 sprint
- Target version changed from Development 2024-03-27 sprint to Development 2024-04-10 sprint
- Tracker changed from Idea to Feature
- Target version changed from Development 2024-04-10 sprint to Development 2024-04-24 sprint
- Target version changed from Development 2024-04-24 sprint to Development 2024-05-08 sprint
- Target version changed from Development 2024-05-08 sprint to Development 2024-06-05 sprint
- Target version changed from Development 2024-06-05 sprint to 439
- Target version changed from 439 to Development 2024-06-19 sprint
- Target version changed from Development 2024-06-19 sprint to Development 2024-07-03 sprint
- Target version changed from Development 2024-07-03 sprint to Development 2024-07-24 sprint
- Target version changed from Development 2024-07-24 sprint to Development 2024-08-07 sprint
- Target version changed from Development 2024-08-07 sprint to Development 2024-08-28 sprint
Also available in: Atom
PDF