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

オープン 初心者向け
  • 何か問題がありますか？
#1,883 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
72/100
issue の種類
ドキュメント
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
markdown, rust
領域
documentation

調査の方向性

STABILITY.md の “Escape hatches” セクションから始め、アクセサーの一覧と除外についての文を、issue で挙げられている 4 つのメソッドと比較してください。big-code-analysis-book/src/library/ast-traversal.md の関連する文脈と、#1871 の changelog エントリーを読んでください。選択したポリシーを反映するように安定性に関する文言を更新してください。これらのアクセサーが対象となる、または除外される理由を明記し、対象外のすべてのメソッドに非公開の型が必要だと示唆しない内容になれば完了です。

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
Rust
スター
32
フォーク
3
平均マージ
9時間 55分
マージ済み PR（30日）
102

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

dekobon/big-code-analysis のほかの issue

dekobon/big-code-analysis の issue をすべて見る

似ている issue

Rust の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。