PyLance-compatible docstrings and clarifications in point.py, grid.py

[Tyler-g-hudson]

There are no code modifications associated with this PR, it is purely a documentation change.

This PR addresses Issue #113 by clarifying the docstrings in point.py and grid.py and reformatting them to be PyLance compatible.

Summary by Sourcery

Clarify and expand docstrings for solid earth tide calculation functions in point and grid modules to be more descriptive and PyLance-compatible.

Documentation:

• Document parameters, return values, units, and examples for point-based solid earth tide calculations.
• Document parameters, return values, and usage examples for grid-based solid earth tide calculations.

[sourcery-ai]

Reviewer's Guide

Refines docstrings for the solid Earth tide point and grid helper functions to be clearer, more explicit about parameter/return types and behavior, and formatted in a style that works well with PyLance, without changing any runtime behavior.

File-Level Changes

Change	Details	Files
Clarified and expanded docstring for calc_solid_earth_tides_point to document parameter units, optional defaults, output behavior, and provide a PyLance-friendly example.	Rewrote parameter section to list each argument separately with explicit Python and NumPy types plus units and default values Documented that dt_out spans at least the dt0–dt1 period and is clamped to step_sec so endpoints may differ slightly Clarified the meaning and units of tide_e, tide_n, and tide_u arrays Reformatted the usage example to be a valid, copy-pastable call signature compatible with PyLance doc rendering	src/pysolid/point.py
Clarified and reformatted docstring for calc_solid_earth_tides_point_per_day to match modern, PyLance-compatible documentation style.	Replaced compact inline parameter description with a structured parameter list including explicit types and units Clarified expected format of date_str as YYYYMMDD and described step_sec as an optional parameter Described the returned dt_out and tide_* arrays with their NumPy dtypes and meanings Updated example to a structured multi-line call that PyLance can parse and present cleanly	src/pysolid/point.py
Updated calc_solid_earth_tides_grid docstring to use structured parameter/return sections and a more explicit example invocation.	Converted free-form parameter description into a parameter list with explicit types, including details of the atr dict keys and step_size semantics Marked display and verbose as optional and documented their default behaviors Specified return array dimensionality and types for tide_e, tide_n, and tide_u Expanded the example to construct a concrete datetime object and show a realistic call signature	src/pysolid/grid.py

Possibly linked issues

• Docstrings for functions in point.py, grid.py are missing some details and are not PyLance compatible #113: PR directly resolves the issue by rewriting those functions’ docstrings with PyLance-compatible, clarified parameter and return descriptions.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• In the docstrings, parameters like lat/lon and dt0/1 are not valid individual names for Pylance-style parsing; consider documenting them as separate entries (lat, lon, dt0, dt1) so tools can reliably associate types and descriptions with actual function parameters.
• There are a couple of typos in the new docstrings (e.g., Deaults instead of Defaults in the step_sec descriptions) that should be corrected to avoid confusion in generated help.
• The calc_solid_earth_tides_grid docstring declares dt_obj as a datetime.datetime, but the example passes a string '20180219'; it would be helpful to align the documented type and the example (or explicitly note both accepted types) for clearer usage guidance.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the docstrings, parameters like `lat/lon` and `dt0/1` are not valid individual names for Pylance-style parsing; consider documenting them as separate entries (`lat`, `lon`, `dt0`, `dt1`) so tools can reliably associate types and descriptions with actual function parameters.
- There are a couple of typos in the new docstrings (e.g., `Deaults` instead of `Defaults` in the `step_sec` descriptions) that should be corrected to avoid confusion in generated help.
- The `calc_solid_earth_tides_grid` docstring declares `dt_obj` as a `datetime.datetime`, but the example passes a string `'20180219'`; it would be helpful to align the documented type and the example (or explicitly note both accepted types) for clearer usage guidance.

## Individual Comments

### Comment 1
<location path="src/pysolid/point.py" line_range="84-85" />
<code_context>
+            latitude/longitude of the point of interest, in degrees
+        dt0/1 : datetime.datetime
+            start/end datetimes
+        step_sec : int, optional
+            Time step, in seconds, of the output. Deaults to 60.
+        display : bool, optional
+            If True, plot the calculated SET. Defaults to False.
</code_context>
<issue_to_address>
**nitpick (typo):** Typo in `step_sec` description ("Deaults" -> "Defaults")

Please update the docstring text accordingly.

```suggestion
        step_sec : int, optional
            Time step, in seconds, of the output. Defaults to 60.
```
</issue_to_address>

### Comment 2
<location path="src/pysolid/grid.py" line_range="30-39" />
<code_context>
+        dt_obj : datetime.datetime
</code_context>
<issue_to_address>
**issue:** Type in `dt_obj` docstring conflicts with example usage

The docstring types `dt_obj` as `datetime.datetime`, but the example passes a string (`'20180219'`). Please either update the type hint to include strings if they’re supported, or change the example to use a `datetime` instance to keep the documentation consistent.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Tyler-g-hudson]

@sourcery-ai review

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• The docstrings mix singular and plural section headers (e.g., Example: vs Examples:) and vary slightly in phrasing; consider standardizing section names and style across these helpers for consistency.
• There is a small typo in calc_solid_earth_tides_point_per_day's docstring (Deaults instead of Defaults), and similarly the examples reference dt.datetime without clarifying that datetime has been imported as import datetime as dt.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The docstrings mix singular and plural section headers (e.g., `Example:` vs `Examples:`) and vary slightly in phrasing; consider standardizing section names and style across these helpers for consistency.
- There is a small typo in `calc_solid_earth_tides_point_per_day`'s docstring (`Deaults` instead of `Defaults`), and similarly the examples reference `dt.datetime` without clarifying that `datetime` has been imported as `import datetime as dt`.

## Individual Comments

### Comment 1
<location path="src/pysolid/point.py" line_range="180-181" />
<code_context>
+            The datetime of the beginning of the SET calculation.
+        dt1 : datetime.datetime
+            The datetime of the end of the SET calculation.
+        step_sec : int, optional
+            Time step, in seconds, of the output. Defaults to 60.
+        display : bool, optional
</code_context>
<issue_to_address>
**nitpick (typo):** Fix the typo in the description of `step_sec` (“Deaults” → “Defaults”).

```suggestion
        step_sec : int, optional
            Time step, in seconds, of the output. Defaults to 60.
```
</issue_to_address>

### Comment 2
<location path="src/pysolid/grid.py" line_range="37-39" />
<code_context>
+                LENGTH/WIDTH
+                X/Y_FIRST
+                X/Y_STEP
+        step_size : float
+            grid step size in meters; fed into the fortran code to speed up the
+            calculation.
+        display : bool, optional
</code_context>
<issue_to_address>
**suggestion:** Mark `step_size` as optional and document its default value to match the function signature.

The signature sets `step_size=1e3`, but the docstring doesn’t show it as optional or document the default. Please update the parameter line to `step_size : float, optional` and mention that it defaults to 1e3 so callers can rely on the documented default.

```suggestion
        step_size : float, optional
            Grid step size in meters; fed into the Fortran code to speed up the
            calculation. Defaults to 1e3.
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}