docs(stability): say where Node's four plain flag accessors stand

Open Beginner friendly
  • Is something wrong?
#1,883 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown, rust
Domain
documentation

Research direction

Start with the “Escape hatches” section in STABILITY.md and compare its accessor list and exclusion sentence with the four methods named in the issue. Read the related context in big-code-analysis-book/src/library/ast-traversal.md and the #1871 changelog entry. Update the stability wording to reflect the chosen policy; done when it states why these accessors are covered or excluded without implying every uncovered method needs an unexported type.

Written by the indexing model from the issue text.

Description

documentation low-priority

Summary

STABILITY.md gives a reason for leaving some Node methods out of the shape contract that does not fit four of them: has_error, is_error, is_missing and, since #1871, is_extra.

What the text says

The "Escape hatches" section lists the Node accessors whose signatures are shape-stable within 2.x: kind, kind_id, id, is_named, utf8_text, the position accessors, child, child_count, child_by_field_name, children, children_with, cursor, parent and previous_sibling. It then says:

Node's remaining methods, the Search walk helpers and the ancestor-chain-taking has_sibling / count_specific_ancestors / parent_grandparent_match, are deliberately not covered. They name Search, Ancestors and Checker, which this crate does not re-export, so they are not callable from big-code-analysis alone

Why it does not fit

has_error, is_error, is_missing and is_extra name none of Search, Ancestors or Checker. They are plain accessors, callable from big-code-analysis alone, and the book documents two of them (big-code-analysis-book/src/library/ast-traversal.md, which also says that anything on Node outside the list is not shape-stable). So they are outside the list for a reason the document does not state.

The Node::is_extra() changelog entry (#1871) says it is outside the list, as its neighbours are, and makes no new commitment.

Decision needed

One of:

  1. Add the four to the list. Their signatures are fn(&self) -> bool, and their values already follow the tree-sitter pin as the listed accessors' do. This is a new stability commitment.
  2. Keep them out, and say so plainly: name them in the "not covered" sentence with the real reason.

Either way the sentence quoted above should stop implying that every uncovered method needs an un-exported type.

Related

#1871, #1376.

Dominant language
Rust
Stars
32
Forks
3
Avg merge
9h 55m
Merged PRs (30d)
102

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from dekobon/big-code-analysis

All issues in dekobon/big-code-analysis

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.