-
Notifications
You must be signed in to change notification settings - Fork 286
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(neon): Move neon-macros docs to re-exports and remove ignore
- Loading branch information
1 parent
167b9d6
commit fdd31f1
Showing
3 changed files
with
150 additions
and
144 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,148 @@ | ||
| //! Helper module to add documentation to macros prior to re-exporting. | ||
| /// Marks a function as the main entry point for initialization in | ||
| /// a Neon module. | ||
| /// | ||
| /// This attribute should only be used _once_ in a module and will | ||
| /// be called each time the module is initialized in a context. | ||
| /// | ||
| /// If a `main` function is not provided, all registered exports will be exported. | ||
| /// | ||
| /// ``` | ||
| /// # use neon::prelude::*; | ||
| /// # fn main() { | ||
| /// #[neon::main] | ||
| /// fn main(mut cx: ModuleContext) -> NeonResult<()> { | ||
| /// // Export all registered exports | ||
| /// neon::registered().export(&mut cx)?; | ||
| /// | ||
| /// let version = cx.string("1.0.0"); | ||
| /// | ||
| /// cx.export_value("version", version)?; | ||
| /// | ||
| /// Ok(()) | ||
| /// } | ||
| /// # } | ||
| /// ``` | ||
| pub use neon_macros::main; | ||
|
|
||
| /// Register an item to be exported by the Neon addon | ||
| /// | ||
| /// ## Exporting constants and statics | ||
| /// | ||
| /// ``` | ||
| /// #[neon::export] | ||
| /// static GREETING: &str = "Hello, Neon!"; | ||
| /// | ||
| /// #[neon::export] | ||
| /// const ANSWER: u8 = 42; | ||
| /// ``` | ||
| /// | ||
| /// ### Renaming an export | ||
| /// | ||
| /// By default, items will be exported with their Rust name. Exports may | ||
| /// be renamed by providing the `name` attribute. | ||
| /// | ||
| /// ``` | ||
| /// #[neon::export(name = "myGreeting")] | ||
| /// static GREETING: &str = "Hello, Neon!"; | ||
| /// ``` | ||
| /// | ||
| /// ### JSON exports | ||
| /// | ||
| /// Complex values may be exported by automatically serializing to JSON and | ||
| /// parsing in JavaScript. Any type that implements `serde::Serialize` may be used. | ||
| /// | ||
| /// ``` | ||
| /// #[neon::export(json)] | ||
| /// static MESSAGES: &[&str] = &["hello", "goodbye"]; | ||
| /// ``` | ||
| /// | ||
| /// ## Exporting functions | ||
| /// | ||
| /// Functions may take any type that implements [`TryFromJs`](crate::types::extract::TryFromJs) as | ||
| /// an argument and return any type that implements [`TryIntoJs`](crate::types::extract::TryIntoJs). | ||
| /// | ||
| /// ``` | ||
| /// #[neon::export] | ||
| /// fn add(a: f64, b: f64) -> f64 { | ||
| /// a + b | ||
| /// } | ||
| /// ``` | ||
| /// | ||
| /// ### Interact with the JavaScript runtime | ||
| /// | ||
| /// More complex functions may need to interact directly with the JavaScript runtime, | ||
| /// for example with [`Context`](crate::context::Context) or handles to JavaScript values. | ||
| /// | ||
| /// Functions may optionally include a [`FunctionContext`](crate::context::FunctionContext) argument. Note | ||
| /// that unlike functions created with [`JsFunction::new`](crate::types::JsFunction), exported function | ||
| /// receive a borrowed context and may require explicit lifetimes. | ||
| /// | ||
| /// ``` | ||
| /// # use neon::prelude::*; | ||
| /// #[neon::export] | ||
| /// fn add<'cx>( | ||
| /// cx: &mut FunctionContext<'cx>, | ||
| /// a: Handle<JsNumber>, | ||
| /// b: Handle<JsNumber>, | ||
| /// ) -> JsResult<'cx, JsNumber> { | ||
| /// let a = a.value(cx); | ||
| /// let b = b.value(cx); | ||
| /// | ||
| /// Ok(cx.number(a + b)) | ||
| /// } | ||
| /// ``` | ||
| /// | ||
| /// ### Exporting a function that uses JSON | ||
| /// | ||
| /// The [`Json`](crate::types::extract::Json) wrapper allows ergonomically handling complex | ||
| /// types that implement `serde::Deserialize` and `serde::Serialize`. | ||
| /// | ||
| /// ``` | ||
| /// # use neon::types::extract::Json; | ||
| /// #[neon::export] | ||
| /// fn sort(Json(mut items): Json<Vec<String>>) -> Json<Vec<String>> { | ||
| /// items.sort(); | ||
| /// Json(items) | ||
| /// } | ||
| /// ``` | ||
| /// | ||
| /// As a convenience, macro uses may add the `json` attribute to automatically | ||
| /// wrap arguments and return values with `Json`. | ||
| /// | ||
| /// ``` | ||
| /// #[neon::export(json)] | ||
| /// fn sort(mut items: Vec<String>) -> Vec<String> { | ||
| /// items.sort(); | ||
| /// items | ||
| /// } | ||
| /// ``` | ||
| /// | ||
| /// ### Tasks | ||
| /// | ||
| /// Neon provides an API for spawning tasks to execute asynchronously on Node's worker | ||
| /// pool. JavaScript may await a promise for completion of the task. | ||
| /// | ||
| /// ``` | ||
| /// # use neon::prelude::*; | ||
| /// #[neon::export] | ||
| /// fn add<'cx>(cx: &mut FunctionContext<'cx>, a: f64, b: f64) -> JsResult<'cx, JsPromise> { | ||
| /// let promise = cx | ||
| /// .task(move || a + b) | ||
| /// .promise(|mut cx, res| Ok(cx.number(res))); | ||
| /// | ||
| /// Ok(promise) | ||
| /// } | ||
| /// ``` | ||
| /// | ||
| /// As a convenience, macro users may indicate that a function should be executed | ||
| /// asynchronously on the worker pool by adding the `task` attribute. | ||
| /// | ||
| /// ``` | ||
| /// #[neon::export(task)] | ||
| /// fn add(a: f64, b: f64) -> f64 { | ||
| /// a + b | ||
| /// } | ||
| /// ``` | ||
| pub use neon_macros::export; |