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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#1,883 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
72/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
markdown, rust
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với phần “Escape hatches” trong STABILITY.md và so sánh danh sách accessor cùng câu nói về các trường hợp loại trừ với bốn phương thức được nêu trong issue. Đọc ngữ cảnh liên quan trong big-code-analysis-book/src/library/ast-traversal.md và mục changelog #1871. Cập nhật cách diễn đạt về tính ổn định để phản ánh chính sách đã chọn; hoàn tất khi nội dung nêu rõ lý do các accessor này được áp dụng hoặc bị loại trừ mà không hàm ý rằng mọi phương thức không được áp dụng đều cần một kiểu chưa được export.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Rust
Star
32
Fork
3
Merge trung bình
9 giờ 55 phút
Pull request đã merge (30 ngày)
102

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của dekobon/big-code-analysis

Tất cả issue của dekobon/big-code-analysis

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.