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

Scripts in dev_tools would benefit from updated and additional documentation #6733

Open
mhucka opened this issue Sep 18, 2024 · 0 comments
Open
Assignees
Labels
area/ci kind/docs Documentation related problems, ideas, requests triage/accepted there is consensus amongst maintainers that this is a real bug or a reasonable feature to add

Comments

@mhucka
Copy link
Contributor

mhucka commented Sep 18, 2024

Description of the issue

Most of the scripts in dev_tools/ do are not described anywhere, most don't support a --help or similar command-line argument, and most either lack a usage description in comments within the file, or what is there is out of date. For example, dev_tools/modules.py has a usage docstring at the top of the file (and prints it if you run it with --help), but the code accepts other arguments that are not mentioned.

It would benefit developers to add a README file to dev_tools/ that summarizes the contents of that directory, and also to add usage info (preferrably via a --help argument if possible, or at least comments at the top of the file) to those scripts that are meant to be invoked from the command line.

How to reproduce the issue

Inspecting the dev_tools/ directory and the code therein, the issue becomes evident.

Cirq version

1.5.0.dev

@mhucka mhucka added the kind/bug-report Something doesn't seem to work. label Sep 18, 2024
@mhucka mhucka self-assigned this Sep 18, 2024
@NoureldinYosri NoureldinYosri added the triage/discuss Needs decision / discussion, bring these up during Cirq Cynque label Sep 18, 2024
@verult verult added kind/docs Documentation related problems, ideas, requests triage/accepted there is consensus amongst maintainers that this is a real bug or a reasonable feature to add area/ci and removed triage/discuss Needs decision / discussion, bring these up during Cirq Cynque kind/bug-report Something doesn't seem to work. labels Oct 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/ci kind/docs Documentation related problems, ideas, requests triage/accepted there is consensus amongst maintainers that this is a real bug or a reasonable feature to add
Projects
None yet
Development

No branches or pull requests

3 participants