Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Display short description from docstring instead of params in usage #290

Conversation

olzhasar-reef
Copy link

No description provided.

@olzhasar-reef olzhasar-reef changed the title Use short description from docstring as usage help Display short description from docstring instead of params in usage help May 7, 2024
@olzhasar-reef olzhasar-reef changed the title Display short description from docstring instead of params in usage help Display short description from docstring instead of params in usage May 7, 2024
Copy link

@mjurbanski-reef mjurbanski-reef left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

usages:
  b2 account   Account management subcommands.
  b2 bucket   Bucket management subcommands.
  b2 file   File management subcommands.
  b2 info   Prints all of the information about the object, but not its contents.
  b2 install-autocomplete   Installs autocomplete for supported shells.
  b2 key   Application keys management subcommands.
  b2 license   Prints the license of B2 Command line tool and all libraries shipped with it.
  b2 ls   Using the file naming convention that / separates folder names from their contents, returns
  b2 replication   Replication rule management subcommands.
  b2 rm   Removes a "folder" or a set of files matching a pattern. Use with caution.
  b2 sync   Copies multiple files from source to destination. Optionally deletes or hides destination
  b2 version   Prints the version number of this tool.

This looks almost good, but:

  • its hard to determine where command ends and where description beings - ideally all would be aligned as they are in git, i.e.
   bisect    Use binary search to find the commit that introduced a bug
   diff      Show changes between commits, commit and working tree, etc
   grep      Print lines matching a pattern
   log       Show commit logs
   show      Show various types of objects
   status    Show the working tree status

or perhaps otherwise clearly marked where command ends

  • b2 ls Using the file naming convention that / separates folder names from their contents, returns - something went very wrong here, same with sync
  • missing towncrier changelog msg

@olzhasar-reef
Copy link
Author

I changed a lot of docstrings to use imperative verb form in the first line. This form arguably better fits the cli help context: more concise and straight to the point.

@mjurbanski-reef mjurbanski-reef merged commit e25c9c1 into reef-technologies:master May 8, 2024
30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants