4

Sorry if this is a dumb question but I am just stuck on how to best document this typed class.

I recently starting working in Scala and am working to clean up some code and add documentation.

I have an API in my project that makes request to other services' APIs and translates the response from that service's API to a Future Result for my project's API.

Sample structure:

object RequestClient {
    def Request(method: String, path: String, queryString: String, body: String = ""): Future[Result] = {
        // Do work here
        return Future[Result]
    }
}

I am trying to document the Request method as follows:

/**
  * Returns [[scala.concurrent.future]] of Response to Some service's API.
  */

But it seems that this will just reference the future class without any mention that it is specifically a Future[] of the type Result.

It seems kinda of an important detail that this is a Result Type (as opposed to an Int String or something else) but if I were to specify it as:

/**
  * Returns [[play.api.mvc.Result]] of Response to Some service's API.
  */

Then it looses the reference to the fact it is a Future[Result].

It seems like might be able to do something like this but it has a smell about it.

/**
  * Returns [[scala.concurrent.future]] `[` [[play.api.mvc.Result]] `]` of Response to Some service's API.
  */

Any suggestions or am I just out of luck and need to pick one?

Thanks in advance for any help.

**update

For clarification I am hoping for something that reads:

Future[Result]

Where clicking the Future text would link to the docs for scala.concurrent.future and clicking the Result text would link to the docs for play.api.mvc.Result

DVS
  • 783
  • 7
  • 25

1 Answers1

3

If I understood what you want, a link with custom text, you can follow a valid link with a space and then your text:

* Returns [[scala.concurrent.future play.api.mvc.Result]]

Edit:

Re-reading the question, my answer isn't what you want. I think your solution is correct.

Keith Pinson
  • 1,725
  • 1
  • 14
  • 17
  • Would this link to the future and result types respectively, or just link to the future type and incude the second part as text? – DVS Jun 28 '16 at 01:22
  • The element after the `[[` and before space is the link, it has to be something that Scaladoc can convert to a http link. Everything that follows the space is text. The example, I gave should be converted to something like, `play.api.mvc.Result` – Keith Pinson Jun 28 '16 at 01:32
  • That makes perfect sense. Knowing it converts to html as you describe, it seems I'll have to just pick one. – DVS Jun 28 '16 at 01:45