Backlogs error: Couldn't find RbRelease with 'id'=69 (ActiveRecord::RecordNotFound)
Actions
Bug #19929
open
Improve documentation in the discovery document
Status:
New
Priority:
Normal
Assigned To:
-
Category:
Documentation
Target version:
-
Start date:
Due date:
% Done:
0%
Estimated time:
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.
Updated by Brett Smith almost 2 years ago
- Related to Support #18799: Strategy to generate Python SDK docstrings based on API docs added
Updated by Brett Smith almost 2 years 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.
Updated by
Actions