From bb123b5ead2bb96fd18434f4aef190b75b47d296 Mon Sep 17 00:00:00 2001 From: yeastplume Date: Tue, 1 Oct 2024 17:34:18 +0000 Subject: [PATCH] Add skeletal macro definition to parse Rustdoc comments --- Cargo.lock | 9 ++++++++ Cargo.toml | 2 +- doc/Cargo.toml | 19 +++++++++++++++ doc/src/lib.rs | 54 +++++++++++++++++++++++++++++++++++++++++++ doc/src/openapi_fn.rs | 54 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 doc/Cargo.toml create mode 100644 doc/src/lib.rs create mode 100644 doc/src/openapi_fn.rs diff --git a/Cargo.lock b/Cargo.lock index dad800c9..d6ca5d1a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1520,6 +1520,15 @@ dependencies = [ "uuid", ] +[[package]] +name = "grin_wallet_doc" +version = "5.4.0-alpha.1" +dependencies = [ + "proc-macro2 1.0.86", + "quote 1.0.37", + "syn 2.0.77", +] + [[package]] name = "grin_wallet_impls" version = "5.4.0-alpha.1" diff --git a/Cargo.toml b/Cargo.toml index 76206e23..1ab3440f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -16,7 +16,7 @@ name = "grin-wallet" path = "src/bin/grin-wallet.rs" [workspace] -members = ["api", "config", "controller", "impls", "libwallet", "util"] +members = ["api", "config", "controller", "impls", "libwallet", "util", "doc"] exclude = ["integration"] [dependencies] diff --git a/doc/Cargo.toml b/doc/Cargo.toml new file mode 100644 index 00000000..5c1a7ad9 --- /dev/null +++ b/doc/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "grin_wallet_doc" +version = "5.4.0-alpha.1" +authors = ["Grin Developers "] +description = "Grin Wallet Documentation Macros" +license = "Apache-2.0" +repository = "https://github.com/mimblewimble/grin-wallet" +keywords = [ "crypto", "grin", "mimblewimble" ] +exclude = ["**/*.grin", "**/*.grin2"] +edition = "2018" + +[lib] +proc-macro = true + +[dependencies] +proc-macro2 = "1.0" +syn = { version = "2.0", features = ["full", "extra-traits"] } +quote = "1.0" + diff --git a/doc/src/lib.rs b/doc/src/lib.rs new file mode 100644 index 00000000..31e83840 --- /dev/null +++ b/doc/src/lib.rs @@ -0,0 +1,54 @@ +// Copyright 2024 The Grin Developers +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +//! proc-macro crate to generate OpenAPI documentation for specified functions + +#![deny(non_upper_case_globals)] +#![deny(non_camel_case_types)] +#![deny(non_snake_case)] +#![deny(unused_mut)] +#![warn(missing_docs)] + +mod openapi_fn; + +use proc_macro::TokenStream; +use proc_macro2::{Group, Ident, Punct, Span, TokenStream as TokenStream2}; +use quote::ToTokens; +use syn::{ + bracketed, + parse::{Parse, ParseStream}, + punctuated::Punctuated, + token::Bracket, + DeriveInput, ExprPath, GenericParam, ItemFn, Lit, LitStr, Member, Token, +}; + +use openapi_fn::{OpenAPIFn, OpenAPIFnAttr}; + +#[proc_macro_attribute] +pub fn derive_openapi_fn(input: TokenStream, item: TokenStream) -> TokenStream { + let fn_attribute = syn::parse_macro_input!(input as OpenAPIFnAttr); + let ast_fn = match syn::parse::(item) { + Ok(ast_fn) => ast_fn, + Err(error) => return error.into_compile_error().into_token_stream().into(), + }; + let path = OpenAPIFn::new(fn_attribute, &ast_fn.sig.ident) + .doc_comments(CommentAttributes::from(&ast_fn.attrs).0); + + let handler = path::handler::Handler { + path, + handler_fn: &ast_fn, + }; + + handler.to_token_stream().into() +} diff --git a/doc/src/openapi_fn.rs b/doc/src/openapi_fn.rs new file mode 100644 index 00000000..7a43e131 --- /dev/null +++ b/doc/src/openapi_fn.rs @@ -0,0 +1,54 @@ +// Copyright 2024 The Grin Developers +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +//! Definitions to generate OpenAPI documentation for specified functions + +use proc_macro2::Ident; +use syn::{ + bracketed, + parse::{Parse, ParseStream}, + LitStr, +}; + +#[derive(Default, Debug)] +pub struct OpenAPIFnAttr {} + +impl OpenAPIFnAttr { + pub fn new(params: String) -> Self { + OpenAPIFnAttr {} + } +} + +pub struct OpenAPIFn<'p> { + openapi_fn_attr: OpenAPIFnAttr, + fn_ident: &'p Ident, +} + +impl<'p> OpenAPIFn<'p> { + pub fn new(openapi_fn_attr: OpenAPIFnAttr, fn_ident: &'p Ident) -> Self { + OpenAPIFn { + openapi_fn_attr, + fn_ident, + } + } +} + +impl Parse for OpenAPIFnAttr { + fn parse(input: ParseStream) -> syn::Result { + let content; + let _ = bracketed!(content in input); + let fn_attr = OpenAPIFnAttr::default(); + Ok(fn_attr) + } +}