Project

General

Profile

Actions

Feature #19929

open

Improve documentation in the discovery document

Added by Brett Smith about 1 year ago. Updated 2 days ago.

Status:
New
Priority:
Normal
Assigned To:
Category:
API
Story points:
1.0

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".


Subtasks 1 (1 open0 closed)

Task #20444: ReviewNewTom CleggActions

Related issues

Related to Arvados - Support #18799: Strategy to generate Python SDK docstrings based on API docsResolvedBrett Smith04/14/2023Actions
Related to Arvados - Bug #3817: [API] Discovery document schema does not include generated fields like job dependenciesNewActions
Related to Arvados - Feature #15397: Declutter the APINewActions
Actions #1

Updated by Brett Smith about 1 year ago

  • Related to Support #18799: Strategy to generate Python SDK docstrings based on API docs added
Actions #2

Updated by Brett Smith about 1 year ago

  • Story points set to 1.0

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.

Actions #3

Updated by Peter Amstutz about 1 year ago

  • Release set to 60
Actions #4

Updated by Brett Smith about 1 year ago

  • 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.

Actions #5

Updated by Brett Smith about 1 year ago

  • Related to Bug #3817: [API] Discovery document schema does not include generated fields like job dependencies added
Actions #6

Updated by Brett Smith 12 months ago

  • Description updated (diff)
Actions #7

Updated by Peter Amstutz 11 months ago

  • Target version changed from To be scheduled to Development 2023-05-10 sprint
Actions #8

Updated by Peter Amstutz 11 months ago

  • Assigned To set to Brett Smith
Actions #9

Updated by Peter Amstutz 11 months ago

  • Target version changed from Development 2023-05-10 sprint to Development 2023-05-24 sprint
Actions #10

Updated by Peter Amstutz 11 months ago

  • Target version changed from Development 2023-05-24 sprint to Development 2023-06-07
Actions #11

Updated by Peter Amstutz 10 months ago

  • Target version changed from Development 2023-06-07 to To be scheduled
Actions #12

Updated by Peter Amstutz 6 months ago

  • Target version changed from To be scheduled to Development 2023-11-29 sprint
Actions #13

Updated by Peter Amstutz 6 months ago

Actions #14

Updated by Peter Amstutz 6 months ago

  • Description updated (diff)
Actions #15

Updated by Peter Amstutz 5 months ago

  • Target version changed from Development 2023-11-29 sprint to Development 2024-01-03 sprint
Actions #16

Updated by Peter Amstutz 4 months ago

  • Target version changed from Development 2024-01-03 sprint to Development 2024-01-17 sprint
Actions #17

Updated by Peter Amstutz 4 months ago

  • Category changed from Documentation to API
  • Tracker changed from Bug to Support
Actions #18

Updated by Peter Amstutz 4 months ago

  • Tracker changed from Support to Idea
Actions #19

Updated by Peter Amstutz 4 months ago

  • Target version changed from Development 2024-01-17 sprint to Development 2024-01-31 sprint
Actions #20

Updated by Peter Amstutz 4 months ago

  • Target version changed from Development 2024-01-31 sprint to Development 2024-02-14 sprint
Actions #21

Updated by Peter Amstutz about 2 months ago

  • Target version changed from Development 2024-02-14 sprint to Development 2024-02-28 sprint
Actions #22

Updated by Peter Amstutz about 1 month ago

  • Target version changed from Development 2024-02-28 sprint to Development 2024-03-13 sprint
Actions #23

Updated by Peter Amstutz 30 days ago

  • Target version changed from Development 2024-03-13 sprint to Development 2024-03-27 sprint
Actions #24

Updated by Peter Amstutz 27 days ago

  • Target version changed from Development 2024-03-27 sprint to Development 2024-04-10 sprint
Actions #25

Updated by Peter Amstutz 27 days ago

  • Tracker changed from Idea to Feature
Actions #26

Updated by Peter Amstutz 2 days ago

  • Target version changed from Development 2024-04-10 sprint to Development 2024-04-24 sprint
Actions

Also available in: Atom PDF