Javadoc link to src/main/resource or src/test/resource file using relative path

Question

I would find it extremely useful if there was a way to put a link in javadoc to a standard resource file that resides in src/main/resources or src/test/resources so that another coder could quickly navigate to the resource file (in this case a JSON file) in IntelliJ.

These files are used in unit tests and need to be modified often as the schema changes.

The answer here Link to text file (resource) in Javadoc does not help as an absolute path would be too fragile.

Is there a way to do the same thing as @see with resources? Something specific to IntelliJ would be great if javadoc itself falls short.

score 7 · Answer 1 · answered Dec 28 '17 at 07:15

No need to mention the absolute path. See my package and class structure below. From a sister package if I follow the URI rules I do a .. to go one folder back and mention it like this. It works! On clicking the url the file opens. Although I have illustrated this in eclipse, I think this should be IDE agnostic.

/**
 * Removes all the stop words like a, for, the etc. from the text. For a
 * full list of stop words check
 * <a href="file:../resources/stopWords.txt">/resources/stopWords.txt</a>
 * 
 * @return String free of all the stop-words
 * @param text
 *            The string to be cleaned, do null check at your end
 */

Unfortunately relative paths don't seem to work in IntelliJ – huyz Aug 06 '23 at 12:14 — huyz, Aug 06 '23 at 12:14

score 3 · Accepted Answer · answered Nov 23 '18 at 09:36

3

Not quite an answer but a feature of IDE:

If you use Intellij IDEA, it is possible out-of-the-box. Where you load the file you must specify the path, right? So you Ctrl+click on a path and Intellij just brings you to the file.

The path is relative to the classpath so you have portability.

It requires all the team members to use Intellij, yes, not a global solution, not a "literal" solution.

Check this:

answered Nov 23 '18 at 09:36

WesternGun

11,303
6
88
157

But a resource isn't relative to the classpath, it's relative to the package it's being loaded in – Novaterata Nov 23 '18 at 12:44
But you put all the JSON under `src/java/resources`, no? If you load with `Class.getResourcesAsStream("/xxx/xxx")`, you specify the relative path of this resource relative to "resources". For example, if you have `/src/java/resources/data/myfile.json`, you load with `getClass().getResourcesAsStream("/data/myfile.json");` – WesternGun Nov 23 '18 at 13:47
That's not a relative path, it begins with a slash. – Novaterata Nov 23 '18 at 14:54
In the parameter of this method, the relative path begins with a `/`. Check another answer of mine: https://stackoverflow.com/questions/16374235/resources-and-config-loading-in-maven-project/46442105#46442105 and the javadoc of this method: https://docs.oracle.com/javase/8/docs/api/ and search "java.lang.Class", `getResourcesAsStream()`. – WesternGun Nov 26 '18 at 08:26
I've been on vacation, I'll check if this works for my use case when I'm in the office tomorrow, thanks for your insight – Novaterata Nov 26 '18 at 14:03

score 3 · Answer 3 · answered Apr 23 '20 at 08:36

This makes a clickable link in IntelliJ IDEA, but only to a directory :-/.

src/test/resources/some/path/

/**
 * {@link some.path}
 */

It doesn't work if you add a filename.ext, nor if a directory is an illegal package name (e.g.: starts with a number).

So far this is best I found. Not great, but still handy to hint static files usage (like external API responses) and provide a link to their location, in tests I found.

score 2 · Answer 4 · answered Mar 17 '20 at 07:14

I found a solution. See 2 Source Files (Javadoc Guide).

Make a directory named as doc-files under any package directory

src/
  main/
    java/
      com/
        doc-files/
        MySource.java   // package com;
        mycompany/
          doc-files/
            some.txt
          Company.java  // package com.mycompany

Put resource files in there.

Now link them link this.

/**
 * <a href="doc-files/some.txt">some</a>
 */
class Company {
}

When the javadoc is built, the link workd.

Note that putting those doc-files directories under the src/main/resource doesn't work.

I should have been clearer in the question. I meant a link in the actual javadoc comment that can be clicked in an IDE like IntelliJ. I don't actually use generated javadoc html, and the resource being in the resources directory would be a requirement — Novaterata, Mar 17 '20 at 16:13

Javadoc link to src/main/resource or src/test/resource file using relative path

4 Answers4

Linked