moonflower 🌺

a documentation generator for C bindings

🛠 configuration

You'll need a config file. You can see a sample one in example.conf. The format is pretty simple.

• input_files{...} - specify a list of comma separated quoted paths to the files you would like to process in lieu of the ....
• output_directory(dir) - again, a quoted path to an output directory. Don't leave a trailing slash -- moonflower will add one for you.
• generate_stylesheet(true|false) - false by default but you can extra specify if you want. Leave it false if you're supplying your own style.css or set to true to use the default one.

And that's it! 🥰

🔥 usage

Moonflower is heavily influenced by doxygen, so the comment format reflects that. It only documents function bindings, with comments like this:

/** <- note the double star opening, that's the signal for a doc comment
 *
 * you can have leading stars if you want to make your comments pretty
 *
 * @module path.to.module
 * ^ this sets the module for this comment !!and all susequent comments!! until another module is set
 *   i recommend that you have a module comment at the top of your file and just do function comments
 *   throughout the rest so you don't need to think about it
 *
 * @fn function_name
 * ^ sets the name of the function currently being documented
 * @brief A brief description
 * ^ gives a brief description, shown in the module summary at the top of the documentation
 *   @param a  The first param
 *   ^ sets a parameter named 'a' with the description 'The first param'
 *   @param[number] b The second param
 *   ^ params can optionally have type annotations
 * @returns[number] a+b
 * ^ describes the return value of the function. Optional, and the type annotation is also optional
 *
 * Other stuff in these comments will be turned into ✨content✨ and added at the end of the description.
 */

The comment shown above would probably get kind of weird, because a non-tagged line following immediately after a tagged line will be wrapped into it (so e.g. param a's description would actually be 'The first param ^ sets a parameter named 'a' with the description 'The first param''). But it's representative. Take a peek at example.c to see it in action.

📜 license

ANTI-CAPITALIST SOFTWARE LICENSE (v 1.4)

Copyright (c) 2023 Kate Swanson

This is anti-capitalist software, released for free use by individuals and organizations that do not operate by capitalist principles.

Permission is hereby granted, free of charge, to any person or organization (the "User") obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, merge, distribute, and/or sell copies of the Software, subject to the following conditions:

1. The above copyright notice and this permission notice shall be included in all copies or modified versions of the Software.

2. The User is one of the following: a. An individual person, laboring for themselves b. A non-profit organization c. An educational institution d. An organization that seeks shared profit for all of its members, and allows non-members to set the cost of their labor

3. If the User is an organization with owners, then all owners are workers and all workers are owners with equal equity and/or equal vote.

4. If the User is an organization, then the User is not law enforcement or military, or working for or under either.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT EXPRESS OR IMPLIED WARRANTY OF ANY KIND, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.