0

This question is related to an issue raised for Maven, which doesn't seem to escape paths forwarded to argument files supported by the JavaDoc-tool on Windows. The problem is that it's unclear from the documentation of JavaDoc itself how paths under Windows should be provided in those files.

The following is for Java 7:

If a filename contains embedded spaces, put the whole filename in double quotes, and double each backslash ("My Files\Stuff.java").

https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles

The following from Java 8:

If a file name contains embedded spaces, then put the whole file name in double quotation marks.

https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

In docs of Java 11 that part is completely missing, no mention of quotes, spaces or backslashes anymore:

https://docs.oracle.com/en/java/javase/11/javadoc/javadoc-command.html#GUID-EFE927BC-DB00-4876-808C-ED23E1AAEF7D

If you have a look at the URIs, in former versions of Java they were Windows-specific, while the last one is not. So I guess things have been refactored and some details of the argument files have been simply lost.

So, I need a place where I can talk to people about those differences in the documentation AND in the end how things are supposed to work on Windows. If backslash is an escape character in paths only and all that stuff. I would simply like to get some awareness from people who might know why the docs lack some details now and maybe even provide those details again.

So who/where do I write to? I don't know if it's Oracle or the OpenJDK project or someone completely different. Thanks!

Thorsten Schöning
  • 3,501
  • 2
  • 25
  • 46
  • Not answering, but some remarks. (1) One can use `/` as path separator under Windows. (2) `doc-files` sub-directories are for javadoc images and such. (3) _I assume you have Windows development with external intranet docs you want to link to._ You could invert things by embedding the javadoc in a wiki. – Joop Eggen Dec 28 '18 at 12:47
  • @JoopEggen In my case the problem was with some `pom.xml` using existing paths generated to be Windows-specific by Maven using placeholders, so one lacks the necessary influence: `-out "${project.build.directory}/resource-info.dat"` – Thorsten Schöning Dec 28 '18 at 12:52

2 Answers2

1

I think, but don't take that authoritatively too lightly, that the javadoc tool is just an optional tool (can anyone show a formal obligation for any JDK to include a javadoc tool implementation ?) with a kind of de-facto standard set by the original owners, Sun thence Oracle.

But de-facto is only de-facto. Meaning formally and strictly speaking, that no JDK implementer has any obligation to make his javadoc tool behave like all the others do.

Erwin Smout
  • 18,113
  • 4
  • 33
  • 52
0

I think the best two places are the javadoc-dev mailinglist as well as the bugs database. Starting at some point in time (9, I guess) the have unified the parsing of the @files across tools. I have failed to find the code in the Mercurial repo last time.

Michael-O
  • 18,123
  • 6
  • 55
  • 121