macro: document make_package

Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>

diff --git a/perlmod-macro/src/lib.rs b/perlmod-macro/src/lib.rs
index cbaceb38705b17d2a0d8203e89bb71fecb103004..72eb3c4542ff7ebd8af1fede60f5fde66868a61e 100644 (file)
--- a/perlmod-macro/src/lib.rs
+++ b/perlmod-macro/src/lib.rs
@@ -56,6 +56,58 @@ pub fn export(attr: TokenStream_1, item: TokenStream_1) -> TokenStream_1 {
 }
 
 /// Proc macro to create a perl package file for rust functions.
+///
+/// This macro will write a perl package/module file into cargo's working directory. (Typically the
+/// manifest directory.)
+///
+/// This macro exists mostly for backward compatibility. When using rustc 1.42 or above, a more
+/// readable and less repetitive code will be produced with the [`package`](module@crate::package)
+/// attribute instead.
+///
+/// This macro always has to be used in conjunction with the [`export!]` macro, like this:
+///
+/// ```
+/// use failure::{bail, Error};
+///
+/// #[export]
+/// fn sum_except_42(a: u32, b: u32) -> Result<u32, Error> {
+///     if a == 42 {
+///         // Errors 'die' in perl, so newlines at the end of error messages make a difference!
+///         bail!("dying on magic number\n");
+///     }
+///
+///     Ok(a + b)
+/// }
+///
+/// #[export(name = "xs_sub_name")]
+/// fn double(a: u32) -> Result<u32, Error> {
+///     Ok(2 * a)
+/// }
+///
+/// make_package! {
+///     // First we need to specify the package, similar to perl's syntax:
+///     package "RSPM::DocTest1";
+///
+///     // The library name is usually derived from the crate name in Cargo.toml automatically.
+///     // So this line is optional:
+///     lib "perlmod_test";
+///
+///     // An optional output file name can be specified as follows:
+///     // (we use this here to prevent doc tests from creating files...)
+///     file_name "/dev/null";
+///
+///     // The list of xsubs we want to export:
+///     subs {
+///         // When only providing the name, default naming convention will be used:
+///         // This is used like: `RSPM::DocTest1::sum_except_42(4, 5);` in perl.
+///         sum_except_42,
+///         // If we used an explicit export name, we need to also explicitly export the renamed
+///         // function here:
+///         // This is used like: `RSPM::DocTest1::double_the_number(5);` in perl.
+///         xs_sub_name as double_the_number,
+///     }
+/// }
+/// ```
 #[proc_macro]
 pub fn make_package(item: TokenStream_1) -> TokenStream_1 {
     let item: TokenStream = item.into();