Documenting a macro-based DSL


#1

I’m rather fascinated with Rust’s macro features. I’m exploring the idea of using macros to create a DSL to provide some ambient tooling around cargo build. Something akin to Ant or Gradle.

My biggest concern is the clear documentation of the DSL. Considering the results of a recent survey regarding important crate evaluation criretia, most of us care deeply about the quality of documentation. I’ve seen some advice in the first version of The Book in a section called Documentation, but from what I can tell, the new version has nothing beyond a brief section on comments.

I’ve seen the official documentation of std lib macros, but is there not a more formal structure that is a best practice especially around the documenting of the different matches and their patterns? Javadoc’s @param and @return spring to mind.