traxys/tree-sitter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #2584 from mgunyho/doc-fixes

Browse source 
doc: Add internal links and fix formatting of Rust docs
This commit is contained in:
Andrew Hlynskyi 2023-08-28 21:10:43 +03:00 • committed by GitHub
commit 9de9396958
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 76 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

32
lib/binding_rust/ffi.rs
View file

@ -18,7 +18,7 @@ use crate::{
use std::{marker::PhantomData, mem::ManuallyDrop, ptr::NonNull, str};
impl Language {
/// Reconstructs a [Language] from a raw pointer.
/// Reconstructs a [`Language`] from a raw pointer.
///
/// # Safety
///
@ -27,14 +27,14 @@ impl Language {
Language(ptr)
}
/// Consumes the [Language], returning a raw pointer to the underlying C structure.
/// Consumes the [`Language`], returning a raw pointer to the underlying C structure.
pub fn into_raw(self) -> *const TSLanguage {
ManuallyDrop::new(self).0
}
}
impl Parser {
/// Reconstructs a [Parser] from a raw pointer.
/// Reconstructs a [`Parser`] from a raw pointer.
///
/// # Safety
///
@ -43,7 +43,7 @@ impl Parser {
Parser(NonNull::new_unchecked(ptr))
}
/// Consumes the [Parser], returning a raw pointer to the underlying C structure.
/// Consumes the [`Parser`], returning a raw pointer to the underlying C structure.
///
/// # Safety
///
@ -56,7 +56,7 @@ impl Parser {
}
impl Tree {
/// Reconstructs a [Tree] from a raw pointer.
/// Reconstructs a [`Tree`] from a raw pointer.
///
/// # Safety
///
@ -65,14 +65,14 @@ impl Tree {
Tree(NonNull::new_unchecked(ptr))
}
/// Consumes the [Tree], returning a raw pointer to the underlying C structure.
/// Consumes the [`Tree`], returning a raw pointer to the underlying C structure.
pub fn into_raw(self) -> *mut TSTree {
ManuallyDrop::new(self).0.as_ptr()
}
}
impl<'tree> Node<'tree> {
/// Reconstructs a [Node] from a raw pointer.
/// Reconstructs a [`Node`] from a raw pointer.
///
/// # Safety
///
@ -81,14 +81,14 @@ impl<'tree> Node<'tree> {
Node(raw, PhantomData)
}
/// Consumes the [Node], returning a raw pointer to the underlying C structure.
/// Consumes the [`Node`], returning a raw pointer to the underlying C structure.
pub fn into_raw(self) -> TSNode {
ManuallyDrop::new(self).0
}
}
impl<'a> TreeCursor<'a> {
/// Reconstructs a [TreeCursor] from a raw pointer.
/// Reconstructs a [`TreeCursor`] from a raw pointer.
///
/// # Safety
///
@ -97,14 +97,14 @@ impl<'a> TreeCursor<'a> {
TreeCursor(raw, PhantomData)
}
/// Consumes the [TreeCursor], returning a raw pointer to the underlying C structure.
/// Consumes the [`TreeCursor`], returning a raw pointer to the underlying C structure.
pub fn into_raw(self) -> TSTreeCursor {
ManuallyDrop::new(self).0
}
}
impl Query {
/// Reconstructs a [Query] from a raw pointer.
/// Reconstructs a [`Query`] from a raw pointer.
///
/// # Safety
///
@ -113,14 +113,14 @@ impl Query {
Query::from_raw_parts(ptr, source)
}
/// Consumes the [Query], returning a raw pointer to the underlying C structure.
/// Consumes the [`Query`], returning a raw pointer to the underlying C structure.
pub fn into_raw(self) -> *mut TSQuery {
ManuallyDrop::new(self).ptr.as_ptr()
}
}
impl QueryCursor {
/// Reconstructs a [QueryCursor] from a raw pointer.
/// Reconstructs a [`QueryCursor`] from a raw pointer.
///
/// # Safety
///
@ -131,14 +131,14 @@ impl QueryCursor {
}
}
/// Consumes the [QueryCursor], returning a raw pointer to the underlying C structure.
/// Consumes the [`QueryCursor`], returning a raw pointer to the underlying C structure.
pub fn into_raw(self) -> *mut TSQueryCursor {
ManuallyDrop::new(self).ptr.as_ptr()
}
}
impl LookaheadIterator {
/// Reconstructs a [LookaheadIterator] from a raw pointer.
/// Reconstructs a [`LookaheadIterator`] from a raw pointer.
///
/// # Safety
///
@ -147,7 +147,7 @@ impl LookaheadIterator {
LookaheadIterator(NonNull::new_unchecked(ptr))
}
/// Consumes the [LookaheadIterator], returning a raw pointer to the underlying C structure.
/// Consumes the [`LookaheadIterator`], returning a raw pointer to the underlying C structure.
pub fn into_raw(self) -> *mut TSLookaheadIterator {
ManuallyDrop::new(self).0.as_ptr()
}

119
lib/binding_rust/lib.rs
View file

@ -78,13 +78,13 @@ pub struct InputEdit {
pub new_end_position: Point,
}
/// A single node within a syntax `Tree`.
/// A single node within a syntax [`Tree`].
#[doc(alias = "TSNode")]
#[derive(Clone, Copy)]
#[repr(transparent)]
pub struct Node<'tree>(ffi::TSNode, PhantomData<&'tree ()>);
/// A stateful object that this is used to produce a `Tree` based on some source code.
/// A stateful object that this is used to produce a [`Tree`] based on some source code.
#[doc(alias = "TSParser")]
pub struct Parser(NonNull<ffi::TSParser>);
@ -105,7 +105,7 @@ type FieldId = NonZeroU16;
/// A callback that receives log messages during parser.
type Logger<'a> = Box<dyn FnMut(LogType, &str) + 'a>;
/// A stateful object for walking a syntax `Tree` efficiently.
/// A stateful object for walking a syntax [`Tree`] efficiently.
#[doc(alias = "TSTreeCursor")]
pub struct TreeCursor<'cursor>(ffi::TSTreeCursor, PhantomData<&'cursor ()>);
@ -145,13 +145,13 @@ impl From<ffi::TSQuantifier> for CaptureQuantifier {
}
}
/// A stateful object for executing a `Query` on a syntax `Tree`.
/// A stateful object for executing a [`Query`] on a syntax [`Tree`].
#[doc(alias = "TSQueryCursor")]
pub struct QueryCursor {
ptr: NonNull<ffi::TSQueryCursor>,
}
/// A key-value pair associated with a particular pattern in a `Query`.
/// A key-value pair associated with a particular pattern in a [`Query`].
#[derive(Debug, PartialEq, Eq)]
pub struct QueryProperty {
pub key: Box<str>,
@ -165,14 +165,14 @@ pub enum QueryPredicateArg {
String(Box<str>),
}
/// A key-value pair associated with a particular pattern in a `Query`.
/// A key-value pair associated with a particular pattern in a [`Query`].
#[derive(Debug, PartialEq, Eq)]
pub struct QueryPredicate {
pub operator: Box<str>,
pub args: Vec<QueryPredicateArg>,
}
/// A match of a `Query` to a particular set of `Node`s.
/// A match of a [`Query`] to a particular set of [`Node`]s.
pub struct QueryMatch<'cursor, 'tree> {
pub pattern_index: usize,
pub captures: &'cursor [QueryCapture<'tree>],
@ -180,7 +180,7 @@ pub struct QueryMatch<'cursor, 'tree> {
cursor: *mut ffi::TSQueryCursor,
}
/// A sequence of `QueryMatch`es associated with a given `QueryCursor`.
/// A sequence of [`QueryMatch`]es associated with a given [`QueryCursor`].
pub struct QueryMatches<'query, 'cursor, T: TextProvider<I>, I: AsRef<[u8]>> {
ptr: *mut ffi::TSQueryCursor,
query: &'query Query,
@ -190,7 +190,7 @@ pub struct QueryMatches<'query, 'cursor, T: TextProvider<I>, I: AsRef<[u8]>> {
_phantom: PhantomData<(&'cursor (), I)>,
}
/// A sequence of `QueryCapture`s associated with a given `QueryCursor`.
/// A sequence of [`QueryCapture`]s associated with a given [`QueryCursor`].
pub struct QueryCaptures<'query, 'cursor, T: TextProvider<I>, I: AsRef<[u8]>> {
ptr: *mut ffi::TSQueryCursor,
query: &'query Query,
@ -208,7 +208,7 @@ where
fn text(&mut self, node: Node) -> Self::I;
}
/// A particular `Node` that has been captured with a particular name within a `Query`.
/// A particular [`Node`] that has been captured with a particular name within a [`Query`].
#[derive(Clone, Copy, Debug)]
#[repr(C)]
pub struct QueryCapture<'tree> {
@ -216,17 +216,17 @@ pub struct QueryCapture<'tree> {
pub index: u32,
}
/// An error that occurred when trying to assign an incompatible `Language` to a `Parser`.
/// An error that occurred when trying to assign an incompatible [`Language`] to a [`Parser`].
#[derive(Debug, PartialEq, Eq)]
pub struct LanguageError {
version: usize,
}
/// An error that occurred in `Parser::set_included_ranges`.
/// An error that occurred in [`Parser::set_included_ranges`].
#[derive(Debug, PartialEq, Eq)]
pub struct IncludedRangesError(pub usize);
/// An error that occurred when trying to create a `Query`.
/// An error that occurred when trying to create a [`Query`].
#[derive(Debug, PartialEq, Eq)]
pub struct QueryError {
pub row: usize,
@ -264,7 +264,7 @@ pub struct LossyUtf8<'a> {
impl Language {
/// Get the ABI version number that indicates which version of the Tree-sitter CLI
/// that was used to generate this `Language`.
/// that was used to generate this [`Language`].
#[doc(alias = "ts_language_version")]
pub fn version(&self) -> usize {
unsafe { ffi::ts_language_version(self.0) as usize }
@ -342,7 +342,8 @@ impl Language {
FieldId::new(id)
}
/// Get the next parse state. Combine this with [lookahead_iterator] to
/// Get the next parse state. Combine this with
/// [`lookahead_iterator`](Language::lookahead_iterator) to
/// generate completion suggestions or valid symbols in error nodes.
///
/// Example:
@ -358,9 +359,9 @@ impl Language {
///
/// This returns `None` if state is invalid for this language.
///
/// Iterating [LookaheadIterator] will yield valid symbols in the given
/// Iterating [`LookaheadIterator`] will yield valid symbols in the given
/// parse state. Newly created lookahead iterators will return the `ERROR`
/// symbol from [LookaheadIterator::current_symbol].
/// symbol from [`LookaheadIterator::current_symbol`].
///
/// Lookahead iterators can be useful to generate suggestions and improve
/// syntax error diagnostics. To get symbols valid in an ERROR node, use the
@ -388,9 +389,9 @@ impl Parser {
/// Returns a Result indicating whether or not the language was successfully
/// assigned. True means assignment succeeded. False means there was a version
/// mismatch: the language was generated with an incompatible version of the
/// Tree-sitter CLI. Check the language's version using [Language::version]
/// and compare it to this library's [LANGUAGE_VERSION](LANGUAGE_VERSION) and
/// [MIN_COMPATIBLE_LANGUAGE_VERSION](MIN_COMPATIBLE_LANGUAGE_VERSION) constants.
/// Tree-sitter CLI. Check the language's version using [`Language::version`]
/// and compare it to this library's [`LANGUAGE_VERSION`](LANGUAGE_VERSION) and
/// [`MIN_COMPATIBLE_LANGUAGE_VERSION`](MIN_COMPATIBLE_LANGUAGE_VERSION) constants.
#[doc(alias = "ts_parser_set_language")]
pub fn set_language(&mut self, language: Language) -> Result<(), LanguageError> {
let version = language.version();
@ -486,12 +487,12 @@ impl Parser {
/// * `old_tree` A previous syntax tree parsed from the same document.
/// If the text of the document has changed since `old_tree` was
/// created, then you must edit `old_tree` to match the new text using
/// [Tree::edit].
/// [`Tree::edit`].
///
/// Returns a [Tree] if parsing succeeded, or `None` if:
/// * The parser has not yet had a language assigned with [Parser::set_language]
/// * The timeout set with [Parser::set_timeout_micros] expired
/// * The cancellation flag set with [Parser::set_cancellation_flag] was flipped
/// Returns a [`Tree`] if parsing succeeded, or `None` if:
/// * The parser has not yet had a language assigned with [`Parser::set_language`]
/// * The timeout set with [`Parser::set_timeout_micros`] expired
/// * The cancellation flag set with [`Parser::set_cancellation_flag`] was flipped
#[doc(alias = "ts_parser_parse")]
pub fn parse(&mut self, text: impl AsRef<[u8]>, old_tree: Option<&Tree>) -> Option<Tree> {
let bytes = text.as_ref();
@ -509,7 +510,7 @@ impl Parser {
/// * `old_tree` A previous syntax tree parsed from the same document.
/// If the text of the document has changed since `old_tree` was
/// created, then you must edit `old_tree` to match the new text using
/// [Tree::edit].
/// [`Tree::edit`].
pub fn parse_utf16(
&mut self,
input: impl AsRef<[u16]>,
@ -533,7 +534,7 @@ impl Parser {
/// * `old_tree` A previous syntax tree parsed from the same document.
/// If the text of the document has changed since `old_tree` was
/// created, then you must edit `old_tree` to match the new text using
/// [Tree::edit].
/// [`Tree::edit`].
pub fn parse_with<T: AsRef<[u8]>, F: FnMut(usize, Point) -> T>(
&mut self,
callback: &mut F,
@ -583,7 +584,7 @@ impl Parser {
/// * `old_tree` A previous syntax tree parsed from the same document.
/// If the text of the document has changed since `old_tree` was
/// created, then you must edit `old_tree` to match the new text using
/// [Tree::edit].
/// [`Tree::edit`].
pub fn parse_utf16_with<T: AsRef<[u16]>, F: FnMut(usize, Point) -> T>(
&mut self,
callback: &mut F,
@ -631,10 +632,10 @@ impl Parser {
/// Instruct the parser to start the next parse from the beginning.
///
/// If the parser previously failed because of a timeout or a cancellation, then
/// by default, it will resume where it left off on the next call to `parse` or
/// other parsing functions. If you don't want to resume, and instead intend to
/// use this parser to parse some other document, you must call `reset` first.
/// If the parser previously failed because of a timeout or a cancellation, then by default, it
/// will resume where it left off on the next call to [`parse`](Parser::parse) or other parsing
/// functions. If you don't want to resume, and instead intend to use this parser to parse some
/// other document, you must call `reset` first.
#[doc(alias = "ts_parser_reset")]
pub fn reset(&mut self) {
unsafe { ffi::ts_parser_reset(self.0.as_ptr()) }
@ -642,7 +643,7 @@ impl Parser {
/// Get the duration in microseconds that parsing is allowed to take.
///
/// This is set via [set_timeout_micros](Parser::set_timeout_micros).
/// This is set via [`set_timeout_micros`](Parser::set_timeout_micros).
#[doc(alias = "ts_parser_timeout_micros")]
pub fn timeout_micros(&self) -> u64 {
unsafe { ffi::ts_parser_timeout_micros(self.0.as_ptr()) }
@ -652,7 +653,7 @@ impl Parser {
/// take before halting.
///
/// If parsing takes longer than this, it will halt early, returning `None`.
/// See `parse` for more information.
/// See [`parse`](Parser::parse) for more information.
#[doc(alias = "ts_parser_set_timeout_micros")]
pub fn set_timeout_micros(&mut self, timeout_micros: u64) {
unsafe { ffi::ts_parser_set_timeout_micros(self.0.as_ptr(), timeout_micros) }
@ -710,7 +711,7 @@ impl Parser {
///
/// If a pointer is assigned, then the parser will periodically read from
/// this pointer during parsing. If it reads a non-zero value, it will halt early,
/// returning `None`. See [parse](Parser::parse) for more information.
/// returning `None`. See [`parse`](Parser::parse) for more information.
#[doc(alias = "ts_parser_set_cancellation_flag")]
pub unsafe fn set_cancellation_flag(&mut self, flag: Option<&AtomicUsize>) {
if let Some(flag) = flag {
@ -770,7 +771,7 @@ impl Tree {
unsafe { ffi::ts_tree_edit(self.0.as_ptr(), &edit) };
}
/// Create a new [TreeCursor] starting from the root of the tree.
/// Create a new [`TreeCursor`] starting from the root of the tree.
pub fn walk(&self) -> TreeCursor {
self.root_node().walk()
}
@ -780,7 +781,7 @@ impl Tree {
///
/// For this to work correctly, this syntax tree must have been edited such that its
/// ranges match up to the new tree. Generally, you'll want to call this method right
/// after calling one of the [Parser::parse] functions. Call it on the old tree that
/// after calling one of the [`Parser::parse`] functions. Call it on the old tree that
/// was passed to parse, and pass the new tree that was returned from `parse`.
#[doc(alias = "ts_tree_get_changed_ranges")]
pub fn changed_ranges(&self, other: &Tree) -> impl ExactSizeIterator<Item = Range> {
@ -881,7 +882,7 @@ impl<'tree> Node<'tree> {
.unwrap()
}
/// Get the [Language] that was used to parse this node's syntax tree.
/// Get the [`Language`] that was used to parse this node's syntax tree.
#[doc(alias = "ts_node_language")]
pub fn language(&self) -> Language {
Language(unsafe { ffi::ts_node_language(self.0) })
@ -995,7 +996,7 @@ impl<'tree> Node<'tree> {
///
/// This method is fairly fast, but its cost is technically log(i), so you
/// if you might be iterating over a long list of children, you should use
/// [Node::children] instead.
/// [`Node::children`] instead.
#[doc(alias = "ts_node_child")]
pub fn child(&self, i: usize) -> Option<Self> {
Self::new(unsafe { ffi::ts_node_child(self.0, i as u32) })
@ -1009,10 +1010,10 @@ impl<'tree> Node<'tree> {
/// Get this node's *named* child at the given index.
///
/// See also [Node::is_named].
/// See also [`Node::is_named`].
/// This method is fairly fast, but its cost is technically log(i), so you
/// if you might be iterating over a long list of children, you should use
/// [Node::named_children] instead.
/// [`Node::named_children`] instead.
#[doc(alias = "ts_node_named_child")]
pub fn named_child(&self, i: usize) -> Option<Self> {
Self::new(unsafe { ffi::ts_node_named_child(self.0, i as u32) })
@ -1020,7 +1021,7 @@ impl<'tree> Node<'tree> {
/// Get this node's number of *named* children.
///
/// See also [Node::is_named].
/// See also [`Node::is_named`].
#[doc(alias = "ts_node_named_child_count")]
pub fn named_child_count(&self) -> usize {
unsafe { ffi::ts_node_named_child_count(self.0) as usize }
@ -1029,7 +1030,7 @@ impl<'tree> Node<'tree> {
/// Get the first child with the given field name.
///
/// If multiple children may have the same field name, access them using
/// [children_by_field_name](Node::children_by_field_name)
/// [`children_by_field_name`](Node::children_by_field_name)
#[doc(alias = "ts_node_child_by_field_name")]
pub fn child_by_field_name(&self, field_name: impl AsRef<[u8]>) -> Option<Self> {
let field_name = field_name.as_ref();
@ -1044,8 +1045,8 @@ impl<'tree> Node<'tree> {
/// Get this node's child with the given numerical field id.
///
/// See also [child_by_field_name](Node::child_by_field_name). You can convert a field name to
/// an id using [Language::field_id_for_name].
/// See also [`child_by_field_name`](Node::child_by_field_name). You can convert a field name to
/// an id using [`Language::field_id_for_name`].
#[doc(alias = "ts_node_child_by_field_id")]
pub fn child_by_field_id(&self, field_id: u16) -> Option<Self> {
Self::new(unsafe { ffi::ts_node_child_by_field_id(self.0, field_id) })
@ -1062,12 +1063,12 @@ impl<'tree> Node<'tree> {
/// Iterate over this node's children.
///
/// A [TreeCursor] is used to retrieve the children efficiently. Obtain
/// a [TreeCursor] by calling [Tree::walk] or [Node::walk]. To avoid unnecessary
/// A [`TreeCursor`] is used to retrieve the children efficiently. Obtain
/// a [`TreeCursor`] by calling [`Tree::walk`] or [`Node::walk`]. To avoid unnecessary
/// allocations, you should reuse the same cursor for subsequent calls to
/// this method.
///
/// If you're walking the tree recursively, you may want to use the `TreeCursor`
/// If you're walking the tree recursively, you may want to use the [`TreeCursor`]
/// APIs directly instead.
pub fn children<'cursor>(
&self,
@ -1084,7 +1085,7 @@ impl<'tree> Node<'tree> {
/// Iterate over this node's named children.
///
/// See also [Node::children].
/// See also [`Node::children`].
pub fn named_children<'cursor>(
&self,
cursor: &'cursor mut TreeCursor<'tree>,
@ -1105,7 +1106,7 @@ impl<'tree> Node<'tree> {
/// Iterate over this node's children with a given field name.
///
/// See also [Node::children].
/// See also [`Node::children`].
pub fn children_by_field_name<'cursor>(
&self,
field_name: &str,
@ -1136,7 +1137,7 @@ impl<'tree> Node<'tree> {
/// Iterate over this node's children with a given field id.
///
/// See also [Node::children_by_field_name].
/// See also [`Node::children_by_field_name`].
pub fn children_by_field_id<'cursor>(
&self,
field_id: FieldId,
@ -1249,7 +1250,7 @@ impl<'tree> Node<'tree> {
&source.as_ref()[self.start_byte()..self.end_byte()]
}
/// Create a new [TreeCursor] starting from this node.
/// Create a new [`TreeCursor`] starting from this node.
#[doc(alias = "ts_tree_cursor_new")]
pub fn walk(&self) -> TreeCursor<'tree> {
TreeCursor(unsafe { ffi::ts_tree_cursor_new(self.0) }, PhantomData)
@ -1258,9 +1259,9 @@ impl<'tree> Node<'tree> {
/// Edit this node to keep it in-sync with source code that has been edited.
///
/// This function is only rarely needed. When you edit a syntax tree with the
/// [Tree::edit] method, all of the nodes that you retrieve from the tree
/// afterward will already reflect the edit. You only need to use [Node::edit]
/// when you have a specific [Node] instance that you want to keep and continue
/// [`Tree::edit`] method, all of the nodes that you retrieve from the tree
/// afterward will already reflect the edit. You only need to use [`Node::edit`]
/// when you have a specific [`Node`] instance that you want to keep and continue
/// to use after an edit.
#[doc(alias = "ts_node_edit")]
pub fn edit(&mut self, edit: &InputEdit) {
@ -1300,7 +1301,7 @@ impl fmt::Debug for Node<'_> {
}
impl<'cursor> TreeCursor<'cursor> {
/// Get the tree cursor's current [Node].
/// Get the tree cursor's current [`Node`].
#[doc(alias = "ts_tree_cursor_current_node")]
pub fn node(&self) -> Node<'cursor> {
Node(
@ -1311,7 +1312,7 @@ impl<'cursor> TreeCursor<'cursor> {
/// Get the numerical field id of this tree cursor's current node.
///
/// See also [field_name](TreeCursor::field_name).
/// See also [`field_name`](TreeCursor::field_name).
#[doc(alias = "ts_tree_cursor_current_field_id")]
pub fn field_id(&self) -> Option<FieldId> {
let id = unsafe { ffi::ts_tree_cursor_current_field_id(&self.0) };
@ -1329,7 +1330,7 @@ impl<'cursor> TreeCursor<'cursor> {
/// Get the numerical field id of this tree cursor's current node.
///
/// See also [field_name](TreeCursor::field_name).
/// See also [`field_name`](TreeCursor::field_name).
#[doc(alias = "ts_tree_cursor_current_depth")]
pub fn depth(&self) -> u32 {
unsafe { ffi::ts_tree_cursor_current_depth(&self.0) }
@ -1439,7 +1440,7 @@ impl<'cursor> TreeCursor<'cursor> {
/// Re-initialize a tree cursor to the same position as another cursor.
///
/// Unlike `reset`, this will not lose parent information and
/// Unlike [`reset`](TreeCursor::reset), this will not lose parent information and
/// allows reusing already created cursors.
#[doc(alias = "ts_tree_cursor_reset_to")]
pub fn reset_to(&mut self, cursor: TreeCursor<'cursor>) {