Skip to content

cchantep/sbt-scaladoc-compiler

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 

SBT scaladoc compiler

This SBT plugin extracts the Scala examples from the Scaladoc comments, and compile the extracted code.

Motivation

Considering a Scaladoc as bellow:

package example

/**
 * Foo
 *
 * {{{
 * import example.Foo
 *
 * Foo.bar()
 * }}}
 */
object Foo {
  def bar(): String = "..."
}

Using this SBT plugin, the code samples between {{{ and }}} (in Scaladoc started with /** and ended with */, in files *.scala) will be extracted as test sources, and so compiled/validated by test compilation.

Get started

This plugin requires SBT 0.13+.

You need to update the project/plugins.sbt.

resolvers ++= Seq(
  "Tatami Releases" at "https://raw.github.com/cchantep/tatami/master/releases")

addSbtPlugin("cchantep" % "sbt-scaladoc-compiler" % "0.3")

See a SBT build using this plugin.

Then, any time test:compile task is executed in SBT, the Scaladoc examples will be compiled along.

In case of SBT Multi-Project

It may be required to disable this plugin on the aggregation if some examples in files of the sub-project require some depen dencies specific to the sub-project (not available at the aggregation time).

lazy val root = Project(id = "...", base = file(".")).
  aggregate(/* ... */).
  disablePlugins(ScaladocExtractorPlugin)

Extraction behaviour

Each code sample need to be standalone:

  • all imports explicitly specified,
  • no call to private members.

In case a code example must be excluded/skipped, the setting scaladocExtractorSkipToken can be used (default: "// not compilable").

/**
 * Lorem ipsum
 *
 * {{{
 * // not compilable: some details why (as also displayed in Scaladoc)
 * foo bar ... anyway it's not compiled (if any good reason)
 * }}}
 */
def foo(s: String): Int = s.size

Build

This is built using SBT.

sbt '^ publishLocal'

Build Status

About

⚙️ This SBT plugin extracts the Scala examples from the Scaladoc comments, and compile the extracted code.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages