akka/akka-http

Improve Java documentation to not refer to Scala code

Open

#1,307 opened on Jul 25, 2017

View on GitHub
 (0 comments) (0 reactions) (0 assignees)Scala (1,311 stars) (598 forks)batch import
1 - triagedhelp wantedt:docst:java

Description

As discussed in #1298 the Java documentation currently includes Scala code snippets when referring to how the Java DSL is defined. We should improve the Java documentation to not use any Scala code by either linking to the Javadoc for the actual definition, providing Java equivalent definitions or rephrasing the documentation to not mention how the API is defined.

Places can be found with the following git grep:

> git grep '@snip .*/javadsl/.*\.scala'
docs/src/main/paradox/java/http/server-side-https-support.md:@@snip [ConnectionContext.scala](../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ConnectionContext.scala) { #https-context-creation }
docs/src/main/paradox/java/http/server-side/websocket-support.md:@@snip [Message.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/model/ws/Message.scala) { #message-model }
docs/src/main/paradox/scala/http/client-side/client-https-support.md::  @@snip [ConnectionContext.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ConnectionContext.scala) { #https-context-creation }
docs/src/main/paradox/scala/http/client-side/client-transport.md::  @@snip [ClientTransport.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ClientTransport.scala) { #client-transport-definition }

Contributor guide

Tech stack
java
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Javadocumentation
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Use the provided `git grep` command to locate all affected documentation files in docs/src/main/paradox/java/http/ and docs/src/main/paradox/scala/http/. For each snippet, decide whether to replace with Java code, link to Javadoc, or rephrase to avoid mentioning API definition. Ensure the Java documentation no longer uses Scala code snippets.