# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.11] - 2026-04-15

### Changed

- Updated repository URLs to reflect new GitHub username (`ryumasai`).

## [0.1.10] - 2026-04-09

### Fixed

- Google parser: section entries at the same indentation level as the section
  header (e.g. zero-indented docstrings) were incorrectly emitted as
  `STRAY_LINE` tokens and silently dropped. A new `body_is_deeper: Option<bool>`
  flag is introduced to record, on the first body line, whether the body is
  indented deeper than the header. The flush condition is now a three-way
  decision: when no body line has been seen yet, flush only on a *strictly*
  shallower line; when the body is deeper than the header, flush at the
  header's indentation level (previous behaviour); when the body is at the
  same level as the header, never flush by indentation (a following section
  header detected by keyword is still recognised). This also makes the parser
  tolerant of slightly mis-indented entries (e.g. 3-space indent when the
  first entry used 4 spaces).

## [0.1.9] - 2026-04-01

### Fixed

- Google parser: stray lines without a preceding blank line were incorrectly
  absorbed into the current section as bogus entries. The `had_blank_in_section`
  flag is removed; instead, any non-blank line at or below the section header's
  indentation level unconditionally flushes the current section, regardless of
  whether a blank line preceded it.
- NumPy parser: the `had_blank_in_section` flush introduced in v0.1.8 incorrectly
  terminated a section when two entries were separated by a blank line (e.g.
  `x : int\n\ny : float` inside a `Parameters` block). The flag is removed;
  NumPy sections now end only when the next `name\n---` header is detected,
  matching the NumPy docstring specification (stray lines inside NumPy sections
  are a known limitation documented in the source).

## [0.1.8] - 2026-03-31

### Fixed

- Google parser: a non-indented line following a blank line inside a section
  was incorrectly absorbed into that section as a bogus entry (e.g. `stray
  line 1` became an `Args` entry) or appended to the preceding
  `Returns` description. The parser now flushes the current section when a
  blank line is followed by a line whose indentation is at or below the
  section header's indentation level.
- NumPy parser: same fix applied. `FreeText` sections (Notes, Examples, etc.)
  are exempt because their body lines legitimately share the same indentation
  level as the section header.

## [0.1.7] - 2026-03-30

### Fixed

- Google parser: prevent panic when an RST-style parameter line (e.g.
  `:param int seconds: …`) is misclassified as a Google-style `Args:` entry.
  `parse_entry_header` now falls through to the bare-name branch whenever
  the colon is at position 0, avoiding an empty `NAME` token.
- `required_token` no longer panics on zero-length (missing) placeholder
  tokens. It now scans children directly and panics only when the token kind
  is completely absent — indicating a structural bug in the parser — rather
  than when the token is present but zero-length.
- NumPy parser: all `build_*_node` functions now emit zero-length placeholder
  tokens for grammatically expected but source-absent tokens, matching the
  convention already used by the Google `build_arg_node`.
  Affected builders: `build_parameter_node` (TYPE), `build_returns_node`
  (RETURN_TYPE), `build_yields_node` (RETURN_TYPE), `build_exception_node`
  (DESCRIPTION), `build_warning_node` (DESCRIPTION), `build_see_also_node`
  (DESCRIPTION), `build_attribute_node` (TYPE).
  Callers can now reliably use `find_missing()` to distinguish
  "expected but absent" from "not applicable".

## [0.1.6] - 2026-03-29

### Added

- `GoogleSectionKind` / `NumPySectionKind` enums — each section now carries a
  `section_kind` property in place of a plain string, enabling exhaustive
  pattern matching in Python.
- `pydocstring.Visitor` base class — all `enter_*` / `exit_*` hook methods are
  declared here; `walk()` now raises `TypeError` if the visitor does not
  subclass `Visitor`.
- `WalkContext` — second argument passed to every `enter_*` / `exit_*` method;
  exposes `line_col(offset)` using a cached line-starts table for O(log n)
  offset-to-line/column conversion.
- `walk()` now returns the visitor instance (typed as `_VisitorT` in stubs),
  enabling one-liner patterns like `collector = walk(doc, Collector())`.
- `PlainDocstring` dispatch in `walk()` — `enter_plain_docstring` /
  `exit_plain_docstring` are now called when walking a plain-style docstring.
- All CST punctuation and structural tokens are now exposed on every node
  object: `open_bracket`, `close_bracket`, `colon`, `directive_marker`,
  `double_colon`, `default_keyword`, `default_separator`, etc.
- `Token.is_missing()` — returns `True` for zero-length placeholder tokens
  inserted by the parser for syntactically absent elements (e.g. an empty-
  bracket type `arg (): desc`).
- `TextRange.is_empty()` — returns `True` when `start == end`.
- `SectionKind` enum (24 variants) on the style-independent model IR —
  replaces the previous string-typed `Section.kind`.
- `Section.unknown_name` getter — returns the raw section header string for
  `SectionKind.UNKNOWN` entries.
- Missing entry wrapper classes added to the Python bindings: `GoogleWarning`,
  `GoogleSeeAlsoItem`, `GoogleAttribute`, `GoogleMethod`, `NumPyDeprecation`,
  `NumPyWarning`, `NumPySeeAlsoItem`, `NumPyReference`, `NumPyAttribute`,
  `NumPyMethod`.
- `NumPyDocstring.deprecation` property — direct accessor for the deprecation
  notice node.
- `__all__` in `pydocstring/__init__.py` listing all public symbols.
- `py.typed` marker (PEP 561) — the package now ships inline type stubs.
- Rust core: `DocstringVisitor` gains an associated `Error` type; all
  `visit_*` methods return `Result<(), Self::Error>`, and `walk_node`
  propagates errors via `?`.

### Changed

- **Python bindings**: `GoogleReturns` renamed to `GoogleReturn`; `GoogleYields`
  renamed to `GoogleYield` — consistent with the singular naming convention
  used by all other entry wrapper types.
- **Python bindings**: `parse()` now returns a typed
  `GoogleDocstring | NumPyDocstring | PlainDocstring` union instead of an opaque
  `object`.
- `Token` now implements `__eq__` and `__hash__` so tokens can be used in sets
  and as dictionary keys.
- `pretty_print()` and `to_model()` on all docstring objects now use a cached
  `Arc<Parsed>` internally, avoiding a redundant re-parse on every call.
- `WalkContext.line_col()` replaces the former `doc.line_col()` method on
  docstring objects; cost reduced from O(offset) linear scan to O(log L)
  binary search.
- Visitor package layout converted to a mixed Rust/Python maturin layout:
  the `Visitor` base class is now defined in `pydocstring/_visitor.py` rather
  than being embedded as a string in the Rust source.
- Rust core: `walk` and `walk_node` are now in `parse::visitor` and
  re-exported from `parse::google` and `parse::numpy`.

### Fixed

- `GoogleSection` and `NumPySection` stubs no longer declare 19 child accessor
  properties that had no corresponding Rust implementation.

### Breaking Changes

**Python bindings**

- Typed `*Section` classes (e.g. `GoogleArgsSection`, `NumPyParametersSection`)
  removed; replaced by a single `GoogleSection` / `NumPySection` with a
  `section_kind` property and per-kind accessor methods (`section.args()`,
  `section.parameters()`, `section.returns()`, etc.).
- `cast_google_*` / `cast_numpy_*` methods on docstring objects removed.
- Visitor hook methods renamed: `visit_*` → `enter_*`, `leave_*` → `exit_*`
  (ANTLR convention).
- `walk()` now requires the visitor to be a subclass of `pydocstring.Visitor`;
  passing an arbitrary object raises `TypeError`.
- `doc.line_col(offset)` removed from `GoogleDocstring`, `NumPyDocstring`, and
  `PlainDocstring`; use `ctx.line_col(offset)` inside a visitor hook instead.
- `Section.kind` is now a `SectionKind` enum value, not a string.
- `GoogleReturns` / `GoogleYields` class names changed to `GoogleReturn` /
  `GoogleYield`.

**Rust core**

- `DocstringVisitor`: all `visit_*` methods now return `Result<(), Self::Error>`
  and require `type Error = ...;` in every implementation. Infallible
  implementations should use `type Error = std::convert::Infallible`.

## [0.1.5] - 2026-03-22

### Added

- `SyntaxKind::GOOGLE_YIELDS` — dedicated node kind for entries inside a Google
  `Yields:` section. Previously these were emitted as `GOOGLE_RETURNS`.
- `SyntaxKind::NUMPY_YIELDS` — dedicated node kind for entries inside a NumPy
  `Yields` section. Previously these were emitted as `NUMPY_RETURNS`.
- `GoogleYields` typed wrapper with `return_type()`, `colon()`, and
  `description()` accessors (analogous to `GoogleReturns`).
- `NumPyYields` typed wrapper with `name()`, `colon()`, `return_type()`, and
  `description()` accessors (analogous to `NumPyReturns`).
- `GoogleSection::yields()` — accessor returning the `GoogleYields` node for
  a Yields section, distinct from `returns()`.
- `NumPySection::yields()` — accessor returning an iterator of `NumPyYields`
  nodes for a Yields section, distinct from `returns()`.
- Python bindings: `SyntaxKind.GOOGLE_YIELDS`, `SyntaxKind.NUMPY_YIELDS`,
  `GoogleYields` class, `NumPyYields` class, `GoogleSection.yields` property,
  and `NumPySection.yields` property.

### Changed

- Google parser: `Yields:` sections now produce `GOOGLE_YIELDS` child nodes
  instead of `GOOGLE_RETURNS`.
- NumPy parser: `Yields` sections now produce `NUMPY_YIELDS` child nodes
  instead of `NUMPY_RETURNS`.
- `to_model` (Google & NumPy): `Yields` sections now use the `yields()`
  accessor on the typed section wrapper rather than sharing the `returns()`
  code path.

## [0.1.4] - 2026-03-20

### Added

- `Style::Plain` — new style variant returned by `detect_style` for docstrings
  that contain no NumPy section underlines or Google section headers (e.g.
  summary-only docstrings, Sphinx-style docstrings).
- `SyntaxKind::PLAIN_DOCSTRING` — root node kind for plain-style parse trees.
- `parse_plain(input)` — lightweight parser that extracts only a `SUMMARY` and
  an optional `EXTENDED_SUMMARY` token from the input, without attempting
  section detection.
- `parse(input)` — unified entry point that calls `detect_style` and dispatches
  to `parse_google`, `parse_numpy`, or `parse_plain` automatically.
- `PlainDocstring` typed wrapper with `summary()` and `extended_summary()`
  accessors (mirrors the existing `GoogleDocstring` / `NumPyDocstring` API).
- Python bindings: `Style.PLAIN`, `SyntaxKind.PLAIN_DOCSTRING`, `PlainDocstring`
  class, and `parse_plain(input)` function.
- Google parser: zero-length `DESCRIPTION` token emitted when a colon is
  present but no description text follows (e.g. `a (int):`, `a:`), and
  zero-length `TYPE` token emitted for empty brackets `()`.
- NumPy parser: zero-length `TYPE` token emitted when a colon is present but
  type text is absent (e.g. `a :`); zero-length `DEFAULT_VALUE` token emitted
  when a default separator is present but no value follows (e.g. `default =`).
  Callers can use `find_missing(KIND)` to detect these absent-but-declared
  slots without inspecting surrounding tokens.
- `examples/parse_auto.rs` — demonstrates the unified `parse()` entry point
  with Google, NumPy, and plain-style inputs.

### Changed

- `detect_style` rewritten as a single O(n) pass; returns `Style::Plain` as the
  fallback instead of `Style::Google`.

## [0.1.3] - 2026-03-19

### Added

- Section name matching now accepts additional singular and alias forms for both
  Google and NumPy styles:
  - `"arg"`, `"param"`, `"keyword arg"`, `"keyword param"`, `"other arg"`,
    `"other param"`, `"method"`, `"reference"` (Google)
  - `"arguments"`, `"argument"`, `"args"`, `"arg"`, `"other arguments"`,
    `"other argument"`, `"other args"`, `"other arg"`, `"attribute"`,
    `"method"`, `"reference"` (NumPy)
  - Common typos tolerated: `"argment"`, `"paramter"` (Google)

### Fixed

- Google parser: arg entries with no description (e.g. `b :`) inside a section
  body were incorrectly classified as new section headers. Fixed by comparing
  the indentation of each line against the current section header's indentation
  and skipping header detection for more-indented lines.

### Changed

- Refactored Google entry header parsing to use a left-to-right confirmation
  algorithm. Handles missing close brackets, missing colons, and text after
  brackets without a colon more robustly. `close_bracket` in `TypeInfo` is now
  `Option<TextRange>` to represent the missing-bracket case.
- Added `rustfmt.toml` (`max_width = 120`) and reformatted all source files.

## [0.1.2] - 2026-03-16

### Added

- `LineColumn` struct (`lineno`, `col`) in `text.rs` for representing
  line/column positions; `lineno` is 1-based, `col` is a 0-based byte offset
  within the line.
- `LineIndex` in `text.rs` — a newline-offset lookup table built from source
  text; converts any `TextSize` byte offset to `LineColumn` in O(log n).
- `Parsed::line_col(offset: TextSize) -> LineColumn` method for resolving
  byte offsets in the syntax tree to line/column positions.
- Python bindings: `LineColumn` class with `lineno` and `col` properties.
  `col` is expressed in **Unicode codepoints** (compatible with Python's
  `ast` module convention) rather than raw bytes.
- Python bindings: `GoogleDocstring.line_col(offset)` and
  `NumPyDocstring.line_col(offset)` methods; `offset` is typically obtained
  from `Token.range.start` or `Token.range.end`.

## [0.1.1] - 2026-03-10

### Added

- Python bindings: `SyntaxKind` enum exposed as `enum.IntEnum`, usable for
  pattern matching on `Token.kind` and `Node.kind` instead of raw strings.

### Fixed

- `emit_google` / `emit_numpy` now correctly apply `base_indent` to all lines
  of the emitted docstring, not just the first line.

### Changed

- Python bindings: `Token.kind` and `Node.kind` now return `SyntaxKind` instead
  of `str`.

## [0.1.0] - 2025-03-09

### Added

- Google style docstring parsing (`parse_google`)
- NumPy style docstring parsing (`parse_numpy`)
- Automatic style detection (`detect_style`)
- Unified model IR (`Docstring`, `Section`, `Parameter`, `Return`, etc.)
- Emit back to Google style (`emit_google`)
- Emit back to NumPy style (`emit_numpy`)
- Full syntax tree (AST) with byte-precise source locations (`TextRange`)
- Tree traversal via `walk` and visitor pattern
- Pretty-print for AST debugging (`pretty_print`)
- Conversion from AST to unified model (`to_model`)
- Support for all standard sections:
  - Parameters / Args / Keyword Args / Other Parameters
  - Returns / Yields
  - Raises / Warns
  - Attributes / Methods
  - See Also / References
  - Deprecation
  - Free-text sections (Notes, Examples, Warnings, Todo, etc.)
- Error-resilient parsing — never panics on malformed input
- Zero external crate dependencies
- Python bindings via PyO3 (`pydocstring-rs`)

[0.1.11]: https://github.com/ryumasai/pydocstring/compare/v0.1.10...v0.1.11
[0.1.10]: https://github.com/ryumasai/pydocstring/compare/v0.1.9...v0.1.10
[0.1.9]: https://github.com/ryumasai/pydocstring/compare/v0.1.8...v0.1.9
[0.1.8]: https://github.com/ryumasai/pydocstring/compare/v0.1.7...v0.1.8
[0.1.7]: https://github.com/ryumasai/pydocstring/compare/v0.1.6...v0.1.7
[0.1.6]: https://github.com/ryumasai/pydocstring/compare/v0.1.5...v0.1.6
[0.1.5]: https://github.com/ryumasai/pydocstring/compare/v0.1.4...v0.1.5
[0.1.4]: https://github.com/ryumasai/pydocstring/compare/v0.1.3...v0.1.4
[0.1.3]: https://github.com/ryumasai/pydocstring/compare/v0.1.2...v0.1.3
[0.1.2]: https://github.com/ryumasai/pydocstring/compare/v0.1.1...v0.1.2
[0.1.1]: https://github.com/ryumasai/pydocstring/compare/v0.1.0...v0.1.1
[0.1.0]: https://github.com/ryumasai/pydocstring/releases/tag/v0.1.0
