Skip to content

Improve server macro documentation #3403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 20, 2025

Conversation

Nathy-bajo
Copy link
Contributor

Enhanced the #[server] macro documentation for improved clarity and usability. Key updates:

  • Expanded explanations of arguments with examples (e.g., prefix, input, output).
  • Showcased advanced features like middleware layers and context sharing.
  • Refactored the macro implementation to replace hardcoded default values for better readability and maintainability.
  • Enhanced error handling with detailed messages to help developers debug issues effectively.

@ealmloff
Copy link
Member

Thanks for working on this! It looks like some unrelated changes to base path leaked into this PR.

The two main fields that need documentation are the input and output fields. Since they effect both the encoding and the trait bounds on the inputs and outputs, it would be useful to include examples with the full server function, instead of just the encoding type. Here are a few examples of the bounds they imply:

/// Setting the type to `StreamingJson` means you need to return something that implements From<JsonStream<T>>
/// where T implements serde::serialize and serde::de::DeserializeOwned
#[server(output = StreamingJson)]
pub async fn json_stream_fn() -> Result<JsonStream<String>, ServerFnError> {
    todo!()
}

/// Setting the type to `StreamingText` means you need to return something that implements From<TextStream>
#[server(output = StreamingText)]
pub async fn text_stream_fn() -> Result<TextStream, ServerFnError> {
    todo!()
}

/// Setting the type to `PostUrl` means you need to return something that implements Serialize and Deserialize.
/// This uses `serde_qs` which imposes the following requirements:
/// - Be less than 5 levels deep
/// - Contain no `serde(flatten)` attributes
#[server(output = PostUrl)]
pub async fn form_fn() -> Result<TextStream, ServerFnError> {
    todo!()
}

@Nathy-bajo
Copy link
Contributor Author

Thanks for working on this! It looks like some unrelated changes to base path leaked into this PR.

The two main fields that need documentation are the input and output fields. Since they effect both the encoding and the trait bounds on the inputs and outputs, it would be useful to include examples with the full server function, instead of just the encoding type. Here are a few examples of the bounds they imply:

/// Setting the type to `StreamingJson` means you need to return something that implements From<JsonStream<T>>
/// where T implements serde::serialize and serde::de::DeserializeOwned
#[server(output = StreamingJson)]
pub async fn json_stream_fn() -> Result<JsonStream<String>, ServerFnError> {
    todo!()
}

/// Setting the type to `StreamingText` means you need to return something that implements From<TextStream>
#[server(output = StreamingText)]
pub async fn text_stream_fn() -> Result<TextStream, ServerFnError> {
    todo!()
}

/// Setting the type to `PostUrl` means you need to return something that implements Serialize and Deserialize.
/// This uses `serde_qs` which imposes the following requirements:
/// - Be less than 5 levels deep
/// - Contain no `serde(flatten)` attributes
#[server(output = PostUrl)]
pub async fn form_fn() -> Result<TextStream, ServerFnError> {
    todo!()
}

I have added the examples as requested @ealmloff 😄

}

pub(crate) fn asset_dir_default() -> PathBuf {
PathBuf::from("assets")
}

pub(crate) fn out_dir_default() -> PathBuf {
PathBuf::from("dist")
Copy link
Contributor

@hackartists hackartists Dec 29, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may break the deployment script due to changing default build artifact directory. How about returning PathBuf for target/dx, which is current out directory described in dioxus_crate.rs:100

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hackartists Hello!
I think this is the PR you're referring to #3393
And I already made that change there

@jkelleyrtp jkelleyrtp requested a review from a team as a code owner June 20, 2025 18:37
@jkelleyrtp jkelleyrtp merged commit 2abe9ed into DioxusLabs:main Jun 20, 2025
18 of 19 checks passed
@jkelleyrtp jkelleyrtp changed the title Fix/server macro defaults Improve server macro documentation Jun 20, 2025
@Nathy-bajo Nathy-bajo deleted the fix/server-macro-defaults branch June 20, 2025 19:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants