Should Javadoc link to project site?

Inspired by @smoyer64’s question on PR #110, I want to discuss whether Javadoc on classes should link to the documentation of the corresponding feature on the project site.

E.g. should “Vintage @Test” link here with a line like this:

/**
 * [...]
 *
 * For more details and examples, see
 * <a href="https://junit-pioneer.org/docs/vintage-test/" target="_top">the documentation on <code>@Test</code></a>
 */

I think this is a good idea. What does everybody else think?

[Bukama]

I vote for including links.

[nipafx]

I think that’s manageable. When creating the documentation for a feature, an entry has to be added to docs-nav.yaml:

  - title: Features
    children:
      - title: "Vintage @Test"
        url: /docs/vintage-test/
      - title: "TempDirectory"
        url: /docs/temp-directory/
      - title: "@DefaultLocale and @DefaultTimeZone"
        url: /docs/default-locale-timezone/
      - title: "@RepeatFailedTest"
        url: /docs/repeat-failed-test

The URL is /docs/$NAME-OF-THE-DOC-FILE. For absolute URL, just prefix with https://junit-pioneer.org.

If we settle on this approach, the contribution documentation needs to be updated anyway - I will make sure to include that explanation.