More documentation tags in metadata


License
Unlicense

Documentation

metadoc

Documentation tags in Clojure metadata.

Check out generated doc

Documentation

Usage

Add following dependency to your project

[metadoc "0.2.0"]

To enable loading separate namespaces with examples from example folder add this folder to classpath (possible in :dev profile).

:source-paths ["example"]

To generate codox docs, add also latest codox dependency and configure it to use metadoc writer.

:codox {:writer metadoc.writers.codox/write-docs
        :source-paths ["src"}

What is that?

Additional metadata tags macros and tooling to enhance :doc documentation for your code. Including:

  • Unit examples - add pure code snippets illustrating your functions. Simple examples can also be tests.
  • Categorization - group your functions in categories (many to many)
  • Constants - show all constants in one block, show also values.

Includes integration with Codox (via custom writer). But is not limited to other tools.

Tags

Tags used in namespace metadata:

  • :metadoc/categories - to map categories keys to names
  • :metadoc/snippets - to store all snippets created with defsnippet

Tags used in var metadata:

  • :metadoc/categories - to store set of categories where var belongs to
  • :metadoc/examples - to store list of examples attached to var

How does it work?

Adding examples

See doc

Adding categorization

Add :metadoc/categories metatag to:

  • variable - containing list/set of categories as keys. Eg. {:metadoc/categories #{:cat1 :cat2}}
  • (optional) namespace - containing map with translation category key to name. Eg. {:metadoc/categories {:cat1 "First category" :cat2 "Second"}}