Skip to content

Correct six docstring entries that contradict the signatures - #7860

Open
dylanpulver wants to merge 2 commits into
openbq-org:developfrom
dylanpulver:hotfix/docstring-parameter-names
Open

dylanpulver wants to merge 2 commits into
openbq-org:developfrom
dylanpulver:hotfix/docstring-parameter-names

Conversation

@dylanpulver

Copy link
Copy Markdown

Pull Request the OpenBB Platform

Description

Six docstring entries contradict the code they describe. Two commits, one per kind.

Parameters that no signature accepts

  • OptionsChainsProperties.strategies takes synthetic_longs and synthetic_shorts. The entries called them synthetic_long and synthetic_short, so strategies(synthetic_long=[...]) raises TypeError. The singular names belong to the sibling synthetic_long and synthetic_short methods on the same class, which is likely where they came from.
  • ChartStyle.__init__ documented a console_style argument. It takes plt_style and user_styles_directory only.

Documented defaults the signature contradicts, all in openbb_figure.py

  • add_trend's secondary_y is bool = False and was documented as None, which is not a value it accepts.
  • add_inchart_volume's row defaults to 1, not 2. Its sibling col already documents 1 correctly.
  • add_corr_plot's max_lag defaults to 20, not 15.

Docstrings only, no behaviour change. add_histplot also documents "by default 15", for bins, where it is correct, so that one is untouched.

How has this been tested?

  • ruff check, ruff format --check and codespell pass on all three files.
  • No runtime path changes, so there is nothing to execute differently. I did not run the full suite.

Checklist

  • I have performed a self-review of my own code.
  • I have commented my code, particularly in hard-to-understand areas.
  • I have adhered to the GitFlow naming convention and my branch name is in the format of feature/feature-name or hotfix/hotfix-name.
  • I ensure that I am following the CONTRIBUTING guidelines.

Two related things I left alone deliberately, happy to send either as a separate PR.

  • app/model/example.py documents multiindex_names on mock_data, where the parameter is multiindex. Renaming alone would leave the type wrong, since the entry reads Optional[List[str]] for a dict[str, Any], so it needs a wording decision rather than a rename.
  • ChartStyle.__init__ still leaves user_styles_directory undocumented. I removed the wrong entry rather than adding a new one, to keep this to corrections.

Three Parameters entries name arguments the code does not accept.

- OptionsChainsProperties.strategies takes `synthetic_longs` and
  `synthetic_shorts`; the entries called them `synthetic_long` and
  `synthetic_short`, so the documented keywords raise TypeError. The
  singular names belong to the sibling methods on the same class, which
  is likely where they came from.
- ChartStyle.__init__ documented a `console_style` argument. It takes
  `plt_style` and `user_styles_directory` only.

Docstrings only, no behaviour change.
Three documented defaults in openbb_figure.py contradict the signature.

- add_trend's `secondary_y` is `bool = False` and was documented as
  None, which is not a value it accepts.
- add_inchart_volume's `row` defaults to 1, not 2. Its sibling `col`
  already documents 1 correctly.
- add_corr_plot's `max_lag` defaults to 20, not 15.

Docstrings only, no behaviour change. add_histplot also documents
"by default 15" for `bins`, which is correct and is left alone.

This branch has not been deployed

No deployments
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.

1 participant