25

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.

4 Answers 4

7

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
 */

enter image description here

Package Structure

1
  • Unfortunately relative paths don't seem to work in IntelliJ
    – huyz
    Aug 6 at 12:14
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:

enter image description here

5
  • But a resource isn't relative to the classpath, it's relative to the package it's being loaded in
    – Novaterata
    Nov 23, 2018 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, 2018 at 13:47
  • That's not a relative path, it begins with a slash.
    – Novaterata
    Nov 23, 2018 at 14:54
  • In the parameter of this method, the relative path begins with a /. Check another answer of mine: stackoverflow.com/questions/16374235/… and the javadoc of this method: docs.oracle.com/javase/8/docs/api and search "java.lang.Class", getResourcesAsStream().
    – WesternGun
    Nov 26, 2018 at 8: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, 2018 at 14:03
3

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.

2

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.

1
  • 1
    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, 2020 at 16:13

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.