1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0

// 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.

use crate::pallet::Def;
use proc_macro2::TokenStream;
use quote::ToTokens;
use syn::{spanned::Spanned, Attribute, Lit, LitStr};

const DOC: &'static str = "doc";
const PALLET_DOC: &'static str = "pallet_doc";

/// Get the documentation file path from the `pallet_doc` attribute.
///
/// Supported format:
/// `#[pallet_doc(PATH)]`: The path of the file from which the documentation is loaded
fn parse_pallet_doc_value(attr: &Attribute) -> syn::Result<DocMetaValue> {
	let lit: syn::LitStr = attr.parse_args().map_err(|_| {
		let msg = "The `pallet_doc` received an unsupported argument. Supported format: `pallet_doc(\"PATH\")`";
		syn::Error::new(attr.span(), msg)
	})?;

	Ok(DocMetaValue::Path(lit))
}

/// Get the value from the `doc` comment attribute:
///
/// Supported formats:
/// - `#[doc = "A doc string"]`: Documentation as a string literal
/// - `#[doc = include_str!(PATH)]`: Documentation obtained from a path
fn parse_doc_value(attr: &Attribute) -> syn::Result<Option<DocMetaValue>> {
	if !attr.path().is_ident(DOC) {
		return Ok(None)
	}

	let meta = attr.meta.require_name_value()?;

	match &meta.value {
		syn::Expr::Lit(lit) => Ok(Some(DocMetaValue::Lit(lit.lit.clone()))),
		syn::Expr::Macro(mac) if mac.mac.path.is_ident("include_str") =>
			Ok(Some(DocMetaValue::Path(mac.mac.parse_body()?))),
		_ =>
			Err(syn::Error::new(attr.span(), "Expected `= \"docs\"` or `= include_str!(\"PATH\")`")),
	}
}

/// Supported documentation tokens.
#[derive(Debug)]
enum DocMetaValue {
	/// Documentation with string literals.
	///
	/// `#[doc = "Lit"]`
	Lit(Lit),
	/// Documentation with `include_str!` macro.
	///
	/// The string literal represents the file `PATH`.
	///
	/// `#[doc = include_str!(PATH)]`
	Path(LitStr),
}

impl ToTokens for DocMetaValue {
	fn to_tokens(&self, tokens: &mut TokenStream) {
		match self {
			DocMetaValue::Lit(lit) => lit.to_tokens(tokens),
			DocMetaValue::Path(path_lit) => {
				let decl = quote::quote!(include_str!(#path_lit));
				tokens.extend(decl)
			},
		}
	}
}

/// Extract the documentation from the given pallet definition
/// to include in the runtime metadata.
///
/// Implement a `pallet_documentation_metadata` function to fetch the
/// documentation that is included in the metadata.
///
/// The documentation is placed on the pallet similar to:
///
/// ```ignore
/// #[pallet]
/// /// Documentation for pallet
/// #[doc = "Documentation for pallet"]
/// #[doc = include_str!("../README.md")]
/// #[pallet_doc("../documentation1.md")]
/// #[pallet_doc("../documentation2.md")]
/// pub mod pallet {}
/// ```
///
/// # pallet_doc
///
/// The `pallet_doc` attribute can only be provided with one argument,
/// which is the file path that holds the documentation to be added to the metadata.
///
/// Unlike the `doc` attribute, the documentation provided to the `proc_macro` attribute is
/// not added to the pallet.
pub fn expand_documentation(def: &mut Def) -> proc_macro2::TokenStream {
	let frame_support = &def.frame_support;
	let type_impl_gen = &def.type_impl_generics(proc_macro2::Span::call_site());
	let type_use_gen = &def.type_use_generics(proc_macro2::Span::call_site());
	let pallet_ident = &def.pallet_struct.pallet;
	let where_clauses = &def.config.where_clause;

	// TODO: Use [drain_filter](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.drain_filter) when it is stable.

	// The `pallet_doc` attributes are excluded from the generation of the pallet,
	// but they are included in the runtime metadata.
	let mut pallet_docs = Vec::with_capacity(def.item.attrs.len());
	let mut index = 0;
	while index < def.item.attrs.len() {
		let attr = &def.item.attrs[index];
		if attr.path().get_ident().map_or(false, |i| *i == PALLET_DOC) {
			pallet_docs.push(def.item.attrs.remove(index));
			// Do not increment the index, we have just removed the
			// element from the attributes.
			continue
		}

		index += 1;
	}

	// Capture the `#[doc = include_str!("../README.md")]` and `#[doc = "Documentation"]`.
	let docs = match def
		.item
		.attrs
		.iter()
		.filter_map(|v| parse_doc_value(v).transpose())
		.collect::<syn::Result<Vec<_>>>()
	{
		Ok(r) => r,
		Err(err) => return err.into_compile_error(),
	};

	// Capture the `#[pallet_doc("../README.md")]`.
	let pallet_docs = match pallet_docs
		.into_iter()
		.map(|attr| parse_pallet_doc_value(&attr))
		.collect::<syn::Result<Vec<_>>>()
	{
		Ok(docs) => docs,
		Err(err) => return err.into_compile_error(),
	};

	let docs = docs.iter().chain(pallet_docs.iter());

	quote::quote!(
		impl<#type_impl_gen> #pallet_ident<#type_use_gen> #where_clauses{

			#[doc(hidden)]
			pub fn pallet_documentation_metadata()
				-> #frame_support::__private::Vec<&'static str>
			{
				#frame_support::__private::vec![ #( #docs ),* ]
			}
		}
	)
}