queries/mutations docs

Author: amrbashir

examples/tanstack-query/src-tauri/src/main.rs

@@ -13,6 +13,7 @@ use thiserror::Error;
 
 // -- Types --
 
+/// A user of the application.
 #[derive(Serialize, Deserialize, Type, Clone)]
 pub struct User {
     id: u32,
@@ -21,6 +22,7 @@ pub struct User {
 }
 
 #[derive(Serialize, Deserialize, Type, Clone)]
+/// A todo item associated with a user.
 pub struct Todo {
     id: u32,
     title: String,
@@ -36,6 +38,7 @@ pub struct AppState {
 
 pub type AppStateMutex = Mutex<AppState>;
 
+/// A simple API error type for demonstration purposes.
 #[derive(Error, Debug, Serialize, Type)]
 #[serde(tag = "type", content = "data")]
 pub enum ApiError {
@@ -47,6 +50,9 @@ pub enum ApiError {
 
 // -- Queries (read operations) --
 
+/// Get a user by ID.
+///
+/// Returns an error if the user does not exist.
 #[tauri::command]
 #[specta::specta]
 fn get_user(state: tauri::State<AppStateMutex>, id: u32) -> Result<User, ApiError> {
@@ -59,13 +65,17 @@ fn get_user(state: tauri::State<AppStateMutex>, id: u32) -> Result<User, ApiErro
         .ok_or(ApiError::NotFound(format!("User {id} not found")))
 }
 
+/// List all users.
 #[tauri::command]
 #[specta::specta]
 fn list_users(state: tauri::State<AppStateMutex>) -> Vec<User> {
     let state = state.lock().unwrap();
     state.users.clone()
 }
 
+/// List todos for a specific user, optionally filtering by title.
+///
+/// If `title` is provided, only todos containing that substring are returned.
 #[tauri::command]
 #[specta::specta]
 fn list_todos(
@@ -121,6 +131,7 @@ fn create_todo(
     Ok(todo)
 }
 
+/// Delete a user by ID, returning an error if the user does not exist.
 #[tauri::command]
 #[specta::specta]
 fn delete_user(state: tauri::State<AppStateMutex>, id: u32) -> Result<(), ApiError> {
@@ -133,6 +144,7 @@ fn delete_user(state: tauri::State<AppStateMutex>, id: u32) -> Result<(), ApiErr
     }
 }
 
+/// Delete a todo by ID, returning an error if the todo does not exist.
 #[tauri::command]
 #[specta::specta]
 fn delete_todo(state: tauri::State<AppStateMutex>, id: u32) -> Result<(), ApiError> {

examples/tanstack-query/src/bindings.ts

@@ -5,12 +5,25 @@ import { queryOptions as __TANSTACK_QUERY_OPTIONS, mutationOptions as __TANSTACK
 
 /** Commands */
 export const commands = {
+	/**
+	 *  Get a user by ID.
+	 * 
+	 *  Returns an error if the user does not exist.
+	 */
 	getUser: (id: number) => typedError<User, ApiError>(__TAURI_INVOKE("get_user", { id })),
+	// List all users.
 	listUsers: () => __TAURI_INVOKE<User[]>("list_users"),
+	/**
+	 *  List todos for a specific user, optionally filtering by title.
+	 * 
+	 *  If `title` is provided, only todos containing that substring are returned.
+	 */
 	listTodos: (userId: number, title: string | null) => __TAURI_INVOKE<Todo[]>("list_todos", { userId, title }),
 	createUser: (name: string, email: string) => typedError<User, ApiError>(__TAURI_INVOKE("create_user", { name, email })),
 	createTodo: (title: string, userId: number) => typedError<Todo, ApiError>(__TAURI_INVOKE("create_todo", { title, userId })),
+	// Delete a user by ID, returning an error if the user does not exist.
 	deleteUser: (id: number) => typedError<null, ApiError>(__TAURI_INVOKE("delete_user", { id })),
+	// Delete a todo by ID, returning an error if the todo does not exist.
 	deleteTodo: (id: number) => typedError<null, ApiError>(__TAURI_INVOKE("delete_todo", { id })),
 };
 
@@ -23,8 +36,19 @@ export const queryKeys = {
 
 /** Queries */
 export const queries = {
+	/**
+	 *  Get a user by ID.
+	 * 
+	 *  Returns an error if the user does not exist.
+	 */
 	getUser: (id: number) => __TANSTACK_QUERY_OPTIONS<User, ApiError>({ queryKey: queryKeys.getUser(id), queryFn: () => unwrapTypedError(commands.getUser(id)) }),
+	// List all users.
 	listUsers: () => __TANSTACK_QUERY_OPTIONS<User[]>({ queryKey: queryKeys.listUsers(), queryFn: () => commands.listUsers() }),
+	/**
+	 *  List todos for a specific user, optionally filtering by title.
+	 * 
+	 *  If `title` is provided, only todos containing that substring are returned.
+	 */
 	listTodos: (userId: number, title: string | null) => __TANSTACK_QUERY_OPTIONS<Todo[]>({ queryKey: queryKeys.listTodos(userId, title), queryFn: () => commands.listTodos(userId, title) }),
 };
 
@@ -40,20 +64,25 @@ export const mutationKeys = {
 export const mutations = {
 	createUser: () => __TANSTACK_MUTATION_OPTIONS<User, ApiError, { name: string, email: string }>({ mutationKey: mutationKeys.createUser(), mutationFn: ({ name, email }: { name: string, email: string }) => unwrapTypedError(commands.createUser(name, email)) }),
 	createTodo: () => __TANSTACK_MUTATION_OPTIONS<Todo, ApiError, { title: string, userId: number }>({ mutationKey: mutationKeys.createTodo(), mutationFn: ({ title, userId }: { title: string, userId: number }) => unwrapTypedError(commands.createTodo(title, userId)) }),
+	// Delete a user by ID, returning an error if the user does not exist.
 	deleteUser: () => __TANSTACK_MUTATION_OPTIONS<null, ApiError, { id: number }>({ mutationKey: mutationKeys.deleteUser(), mutationFn: ({ id }: { id: number }) => unwrapTypedError(commands.deleteUser(id)) }),
+	// Delete a todo by ID, returning an error if the todo does not exist.
 	deleteTodo: () => __TANSTACK_MUTATION_OPTIONS<null, ApiError, { id: number }>({ mutationKey: mutationKeys.deleteTodo(), mutationFn: ({ id }: { id: number }) => unwrapTypedError(commands.deleteTodo(id)) }),
 };
 
 /* Types */
+// A simple API error type for demonstration purposes.
 export type ApiError = { type: "NotFound"; data: string } | { type: "Internal"; data: string };
 
+// A todo item associated with a user.
 export type Todo = {
 	id: number,
 	title: string,
 	completed: boolean,
 	user_id: number,
 };
 
+// A user of the application.
 export type User = {
 	id: number,
 	name: string,

src/lang/js_ts.rs

@@ -307,31 +307,7 @@ fn runtime(
 
             let mut field = Field::new(define(format!("({fn_arguments}) => {body}")).into());
             field.set_deprecated(command.deprecated().cloned());
-            field.set_docs({
-                let mut docs = command.docs().to_string();
-
-                if jsdoc {
-                    if !docs.is_empty() {
-                        docs.push('\n');
-                    }
-
-                    docs.push_str(
-                        &arguments
-                            .iter()
-                            .map(|(name, dt)| format!("@param {{{dt}}} {name}"))
-                            .collect::<Vec<_>>()
-                            .join("\n"),
-                    );
-
-                    if !arguments.is_empty() {
-                        docs.push('\n');
-                    }
-
-                    docs.push_str("@returns {string} myName");
-                }
-
-                docs.into()
-            });
+            field.set_docs(build_command_docs(command, &arguments, jsdoc));
             s = s.field(command.name().to_lower_camel_case(), field);
         }
 
@@ -403,8 +379,10 @@ fn runtime(
                     "({fn_arguments}) => __TANSTACK_QUERY_OPTIONS{generics}({{ queryKey: queryKeys.{command_name}({call_args}), queryFn: () => {query_fn_body} }})"
                 );
 
-                queries_struct = queries_struct
-                    .field(command_name.clone(), Field::new(define(query_body).into()));
+                let mut field = Field::new(define(query_body).into());
+                field.set_deprecated(command.deprecated().cloned());
+                field.set_docs(build_command_docs(command, &arguments, jsdoc));
+                queries_struct = queries_struct.field(command_name.clone(), field);
             }
 
             emit_struct_export(
@@ -478,10 +456,10 @@ fn runtime(
                     "() => __TANSTACK_MUTATION_OPTIONS{generics}({{ mutationKey: mutationKeys.{command_name}(), mutationFn: ({mutation_fn_param}) => {mutation_fn_body} }})"
                 );
 
-                mutations_struct = mutations_struct.field(
-                    command_name.clone(),
-                    Field::new(define(mutation_body).into()),
-                );
+                let mut field = Field::new(define(mutation_body).into());
+                field.set_deprecated(command.deprecated().cloned());
+                field.set_docs(build_command_docs(command, &arguments, jsdoc));
+                mutations_struct = mutations_struct.field(command_name.clone(), field);
             }
 
             emit_struct_export(
@@ -623,6 +601,37 @@ fn runtime(
     Ok(Cow::Owned(out))
 }
 
+/// Build the doc comment for a command, including `@param` annotations for each argument if `jsdoc` is true.
+fn build_command_docs(
+    command: &Function,
+    arguments: &[(String, String)],
+    jsdoc: bool,
+) -> Cow<'static, str> {
+    let mut docs = command.docs().to_string();
+
+    if jsdoc {
+        if !docs.is_empty() {
+            docs.push('\n');
+        }
+
+        docs.push_str(
+            &arguments
+                .iter()
+                .map(|(name, dt)| format!("@param {{{dt}}} {name}"))
+                .collect::<Vec<_>>()
+                .join("\n"),
+        );
+
+        if !arguments.is_empty() {
+            docs.push('\n');
+        }
+
+        docs.push_str("@returns {string} myName");
+    }
+
+    docs.into()
+}
+
 /// Collect command arguments as (camelCase name, rendered type) pairs.
 fn collect_arguments(
     command: &Function,