From 8515986b73a1833ba718c050e6aaaf472b2d4ef9 Mon Sep 17 00:00:00 2001 From: ObserverOfTime Date: Wed, 23 Oct 2024 19:29:01 +0300 Subject: [PATCH] docs(rust): document optional features --- cli/loader/Cargo.toml | 4 ++++ cli/loader/src/lib.rs | 4 ++++ lib/Cargo.toml | 7 ++++++- lib/binding_rust/README.md | 2 +- lib/binding_rust/lib.rs | 27 ++++++++++++++++++--------- 5 files changed, 33 insertions(+), 11 deletions(-) diff --git a/cli/loader/Cargo.toml b/cli/loader/Cargo.toml index 8c5b160b..845070d9 100644 --- a/cli/loader/Cargo.toml +++ b/cli/loader/Cargo.toml @@ -12,6 +12,10 @@ license.workspace = true keywords.workspace = true categories.workspace = true +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] + [lints] workspace = true diff --git a/cli/loader/src/lib.rs b/cli/loader/src/lib.rs index c827243f..a1b36fa2 100644 --- a/cli/loader/src/lib.rs +++ b/cli/loader/src/lib.rs @@ -1,4 +1,5 @@ #![doc = include_str!("../README.md")] +#![cfg_attr(docsrs, feature(doc_cfg))] #[cfg(any(feature = "tree-sitter-highlight", feature = "tree-sitter-tags"))] use std::ops::Range; @@ -406,6 +407,7 @@ impl Loader { } #[cfg(feature = "tree-sitter-highlight")] + #[cfg_attr(docsrs, doc(cfg(feature = "tree-sitter-highlight")))] pub fn configure_highlights(&mut self, names: &[String]) { self.use_all_highlight_names = false; let mut highlights = self.highlight_names.lock().unwrap(); @@ -415,6 +417,7 @@ impl Loader { #[must_use] #[cfg(feature = "tree-sitter-highlight")] + #[cfg_attr(docsrs, doc(cfg(feature = "tree-sitter-highlight")))] pub fn highlight_names(&self) -> Vec { self.highlight_names.lock().unwrap().clone() } @@ -1332,6 +1335,7 @@ impl Loader { } #[cfg(feature = "wasm")] + #[cfg_attr(docsrs, doc(cfg(feature = "wasm")))] pub fn use_wasm(&mut self, engine: &tree_sitter::wasmtime::Engine) { *self.wasm_store.lock().unwrap() = Some(tree_sitter::WasmStore::new(engine).unwrap()); } diff --git a/lib/Cargo.toml b/lib/Cargo.toml index aec708e1..3337302b 100644 --- a/lib/Cargo.toml +++ b/lib/Cargo.toml @@ -31,13 +31,18 @@ include = [ "/include/tree_sitter/api.h", ] +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] +targets = ["x86_64-unknown-linux-gnu", "x86_64-pc-windows-gnu"] + [lints] workspace = true [features] default = ["std"] std = ["regex/std", "regex/perf", "regex-syntax/unicode"] -wasm = ["wasmtime-c-api"] +wasm = ["std", "wasmtime-c-api"] [dependencies] regex = { version = "1.10.6", default-features = false, features = ["unicode"] } diff --git a/lib/binding_rust/README.md b/lib/binding_rust/README.md index ce3b3083..602f647b 100644 --- a/lib/binding_rust/README.md +++ b/lib/binding_rust/README.md @@ -113,4 +113,4 @@ assert_eq!( - Error types implement the `std::error:Error` trait. - `regex` performance optimizations are enabled. - The DOT graph methods are enabled. -- **wasm** - This feature is enabled for Wasm targets. `tree-sitter` to be built for Wasm targets using the `wasmtime-c-api` crate. +- **wasm** - This feature allows `tree-sitter` to be built for Wasm targets using the `wasmtime-c-api` crate. diff --git a/lib/binding_rust/lib.rs b/lib/binding_rust/lib.rs index e70f2fc3..9b6852fe 100644 --- a/lib/binding_rust/lib.rs +++ b/lib/binding_rust/lib.rs @@ -1,5 +1,7 @@ #![doc = include_str!("./README.md")] #![cfg_attr(not(feature = "std"), no_std)] +#![cfg_attr(docsrs, feature(doc_cfg))] + pub mod ffi; mod util; @@ -22,7 +24,7 @@ use core::{ }; #[cfg(feature = "std")] use std::error; -#[cfg(all(feature = "std", any(unix, target_os = "wasi")))] +#[cfg(all(unix, feature = "std"))] use std::os::fd::AsRawFd; #[cfg(all(windows, feature = "std"))] use std::os::windows::io::AsRawHandle; @@ -33,6 +35,7 @@ use tree_sitter_language::LanguageFn; #[cfg(feature = "wasm")] mod wasm_language; #[cfg(feature = "wasm")] +#[cfg_attr(docsrs, doc(cfg(feature = "wasm")))] pub use wasm_language::*; /// The latest ABI version that is supported by the current version of the @@ -477,9 +480,7 @@ impl Parser { /// 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. + /// [`LANGUAGE_VERSION`] and [`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(); @@ -560,6 +561,7 @@ impl Parser { #[doc(alias = "ts_parser_print_dot_graphs")] #[cfg(not(target_os = "wasi"))] #[cfg(feature = "std")] + #[cfg_attr(docsrs, doc(cfg(feature = "std")))] pub fn print_dot_graphs( &mut self, #[cfg(unix)] file: &impl AsRawFd, @@ -584,6 +586,9 @@ impl Parser { /// Stop the parser from printing debugging graphs while parsing. #[doc(alias = "ts_parser_print_dot_graphs")] + #[cfg(not(target_os = "wasi"))] + #[cfg(feature = "std")] + #[cfg_attr(docsrs, doc(cfg(feature = "std")))] pub fn stop_printing_dot_graphs(&mut self) { unsafe { ffi::ts_parser_print_dot_graphs(self.0.as_ptr(), -1) } } @@ -1112,6 +1117,7 @@ impl Tree { #[doc(alias = "ts_tree_print_dot_graph")] #[cfg(not(target_os = "wasi"))] #[cfg(feature = "std")] + #[cfg_attr(docsrs, doc(cfg(feature = "std")))] pub fn print_dot_graph( &self, #[cfg(unix)] file: &impl AsRawFd, @@ -1522,7 +1528,7 @@ impl<'tree> Node<'tree> { /// Get this node's child containing `descendant`. This will not return /// the descendant if it is a direct child of `self`, for that use - /// [`Node::child_contains_descendant`]. + /// [`Node::child_with_descendant`]. #[doc(alias = "ts_node_child_containing_descendant")] #[must_use] #[deprecated(since = "0.24.0", note = "Prefer child_with_descendant instead")] @@ -3307,20 +3313,23 @@ static mut FREE_FN: unsafe extern "C" fn(ptr: *mut c_void) = free; /// This function uses FFI and mutates a static global. #[doc(alias = "ts_set_allocator")] pub unsafe fn set_allocator( - new_malloc: Option *mut c_void>, - new_calloc: Option *mut c_void>, - new_realloc: Option *mut c_void>, - new_free: Option, + new_malloc: Option *mut c_void>, + new_calloc: Option *mut c_void>, + new_realloc: Option *mut c_void>, + new_free: Option, ) { FREE_FN = new_free.unwrap_or(free); ffi::ts_set_allocator(new_malloc, new_calloc, new_realloc, new_free); } #[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] impl error::Error for IncludedRangesError {} #[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] impl error::Error for LanguageError {} #[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] impl error::Error for QueryError {} unsafe impl Send for Language {}