Is it possible in java, above the usual method, to add javaDoc @see, which will reference the JUnit test

Question

There is a Cube class. His absolute path: D:/My_projects/my_project/src/main/java/com/Cube.java

There is a method there:

public double get_volume() { ... }

There is a JUnit Test to check the code - Test_cube His absolute path: D:/My_projects/my_project/src/test/java/com/Test_cube.java

There is a method there:

@Test
public void get_volume() { ... }

The question is: is it possible to make the @see tag from the JavaDoc in the Cube class refer to a test method?

That's what we have now:

/**
 * @see com.Test_cube#get_volume()
 */
public double get_volume() { ... }

I wrote it that way, and it doesn't link. @see looks just like text, not a link. If I write src.test.java.Test_cube#get_volume(), then nothing will happen. That is, as if you can't do this in JavaDoc, refer to methods in other packages

Conceptually this is wrong. The specification of the behavior of a method should be in the method documentation, not in the test documentation. — Stephen C
– Stephen C, Commented Aug 16, 2024 at 1:29
As to why it is not generating links ... my guess is that the test classes are not on the classpath when you run javadoc on your normal classes. (Because dependencies are not supposed to go in that direction. Tests depend on tested, not the other way around.) — Stephen C
– Stephen C, Commented Aug 16, 2024 at 1:32
The reason I asked this question is because I have some methods that I would like to explain what and how to run. To do this, I directly write a block of code in JavaDoc inside <pre></pre> But the code gets scarier from this. Besides, why, if I have already written tests for this a long time. Which can be referenced. — bufferum
– bufferum, Commented Aug 16, 2024 at 2:15
I don't buy that explanation. But ... whatever ... I think I've explained to you why the @see tags are not working. (You could submit a bug report against your build tool for this, but I doubt it would gain much traction.) — Stephen C
– Stephen C, Commented Aug 16, 2024 at 3:10
You can make that work. One liability is if you publish your Javadoc or your code, you may not want to publish your tests to the same audience. They should really trust that your code works and shouldn’t take any interest in the existence of tests, even less how the tests work. Also be aware that if a link is generated, it’s a link to the Javadoc of the test method, probably not interesting. It’s not a link to the source code of the test, where you may read how the production method is supposed to behave. So what would be the value? — Anonymous
– Anonymous, Commented Aug 16, 2024 at 7:23

Mark Rotteveel · Accepted Answer · 2024-08-16 07:31:12Z

2

Code in test depends on code in main, not the other way around. This among other things, makes it impossible for your main code to accidentally reference to or depend on test code. This also means that code in main cannot link to code in test through Javadoc.

In other words, what you want is not possible, and shouldn't be possible.

As an aside, the main purpose of Javadoc is to be able to generate HTML documentation, and doing what you're trying to do would require to merge the Javadoc of the test classes with those of the main classes, which is not what you - generally - want. The javadoc tool itself would make it possible to do this for generating the HTML, by pointing to both main and test as the location of sources (using -source-path), but your IDE itself will not entertain this possibility for the reasons stated above.

edited Aug 16, 2024 at 7:31

answered Aug 16, 2024 at 7:26

Mark Rotteveel

110k240 gold badges160 silver badges232 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

Is it possible in java, above the usual method, to add javaDoc @see, which will reference the JUnit test

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related