akka/akka-http

Create `@example` "include" pre-processor feature for java/scala-doc

Open

#11 opened on Aug 26, 2016

View on GitHub
 (12 comments) (0 reactions) (1 assignee)Scala (1,311 stars) (598 forks)batch import
1 - triagedhelp wanted

Description

We want to use this to power examples for all directives. It will make it easier to maintain the directive docs and would also address https://github.com/akka/akka/issues/18660

The idea is to keep examples somewhere where they are compiled as usual. Then we'd put a reference to an example directly into the scaladoc and then have a preprocessor (on sbt or scaladoc/javadoc level) that includes the snippet at that point into the scaladocs.

Example would be:

class ThingDirectives {

/**
 * Does things.
 *
 * @example $root/akka-http-docs/blabla/ExampleDirectivesSpec.scala#example
 */
def example(t: String): Directive0 = ???
}

It should:

  • Fail compilation if include does not exist
  • Work for Scaladoc and Javadoc
  • create a <code> block basically
  • in Scaladoc there was an example feature I believe, check that
  • allow us to move all directive method docs into scaladoc, so we don't have to maintain explicit docs pages for each of them

Contributor guide

Tech stack
scalajava
Domain
documentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
3-5 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
ScalaDoc knowledgeJavadoc knowledgeSBT build toolPreprocessor concepts
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
35
Research direction
Investigate the existing Scaladoc @example feature and its limitations. Review the referenced issue akka/akka#18660 for context. Look into how SBT can be extended with a preprocessor plugin. Examine the directory structure of akka http docs for potential example locations. Assess feasibility of integrating with both Scaladoc and Javadoc.
Create `@example` "include" pre-processor feature for java/scala-doc · akka/akka-http#11 | Good First Issue