Skip to content

WIP: Implement auto-documenting routes #1624

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.

Sign up for GitHub

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

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

WIP: Implement auto-documenting routes #1624

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion core/codegen/src/attribute/route/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -296,6 +296,25 @@ fn sentinels_expr(route: &Route) -> TokenStream {
quote!(::std::vec![#(#sentinel),*])
}

fn schemas_expr(route: &Route) -> TokenStream {
let ret_ty = match route.handler.sig.output {
syn::ReturnType::Default => None,
syn::ReturnType::Type(_, ref ty) => Some(ty.with_stripped_lifetimes())
};

let eligible_types = route.guards()
.map(|guard| &guard.ty)
.chain(ret_ty.as_ref().into_iter());

let schema = eligible_types.map(|ty| {
define_spanned_export!(ty.span() => _doc);

quote_spanned!(ty.span() => #_doc::resolve_doc!(#ty))
});

quote!(::std::vec![#(#schema),*])
}

fn codegen_route(route: Route) -> Result<TokenStream> {
use crate::exports::*;

Expand All @@ -305,8 +324,9 @@ fn codegen_route(route: Route) -> Result<TokenStream> {
let query_guards = query_decls(&route);
let data_guard = route.data_guard.as_ref().map(data_guard_decl);

// Extract the sentinels from the route.
// Extract the sentinels and schemas from the route.
let sentinels = sentinels_expr(&route);
let schemas = schemas_expr(&route);

// Gather info about the function.
let (vis, handler_fn) = (&route.handler.vis, &route.handler);
Expand All @@ -319,6 +339,9 @@ fn codegen_route(route: Route) -> Result<TokenStream> {
let rank = Optional(route.attr.rank);
let format = Optional(route.attr.format.as_ref());

// Get the doc comment
let docstring = &route.docstring;
Copy link
Member

Choose a reason for hiding this comment

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

No need to separate this. Group it with the rest.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Do you mean add it to the StaticInfo::schemas field?

Copy link
Member

@SergioBenitez SergioBenitez May 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Sorry, I just need style wise. Basically to just remove the whitespace and comment.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Right okay


Ok(quote! {
#handler_fn

Expand Down Expand Up @@ -353,6 +376,8 @@ fn codegen_route(route: Route) -> Result<TokenStream> {
format: #format,
rank: #rank,
sentinels: #sentinels,
schemas: #schemas,
docstring: #docstring,
}
}

Expand Down
6 changes: 5 additions & 1 deletion core/codegen/src/attribute/route/parse.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ pub struct Route {
pub handler: syn::ItemFn,
/// The parsed arguments to the user's function.
pub arguments: Arguments,
/// The doc comment describing this route
pub docstring: String,
}

type ArgumentMap = IndexMap<Name, (syn::Ident, syn::Type)>;
Expand Down Expand Up @@ -209,9 +211,11 @@ impl Route {
})
.collect();

let docstring = String::from_attrs("doc", &handler.attrs)?.join("\n");
Copy link
Member

Choose a reason for hiding this comment

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

Did you determine if we need the \n?

Copy link
Contributor Author

@ThouCheese ThouCheese May 4, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

I believe we need it, because Rust comments are markdown, which is also supported for OpenApi and RAML. Markdown is a newline sensitive format: # title \n remainder\n is not the same as # title remainder, so removing the newline would alter the structure of the docs.

Copy link
Member

@SergioBenitez SergioBenitez May 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

My question is really whether rustdoc already inserts a new line or whether it infers one based on having multiple attributes. You should be able to easily check. We only need the new line here if it is inferred.


diags.head_err_or(Route {
attr, path_params, query_params, data_guard, request_guards,
handler, arguments,
handler, arguments, docstring
})
}
}
Expand Down
1 change: 1 addition & 0 deletions core/codegen/src/exports.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ define_exported_paths! {
_route => ::rocket::route,
_catcher => ::rocket::catcher,
_sentinel => ::rocket::sentinel,
_doc => ::rocket::doc,
_log => ::rocket::log,
_form => ::rocket::form::prelude,
_http => ::rocket::http,
Expand Down
Loading