18

The Javadoc for enums always display its constants using alphabetic ordering. Is it possible to change that?

For instance, the javadoc for java.time.DayOfWeek would look better if the constants weren't displayed as FRIDAY, MONDAY, SATURDAY, SUNDAY, THURSDAY TUESDAY, WEDNESDAY...

bruno
  • 2,213
  • 1
  • 19
  • 31
  • 2
    I don't know if it's possible but the new Java time javadoc has not been able to do that: http://docs.oracle.com/javase/8/docs/api/java/time/DayOfWeek.html – wha'eve' May 23 '14 at 11:47
  • 1
    I'm not really don't understand this question. – Abimaran Kugathasan May 23 '14 at 11:57
  • 1
    Your enum example, seems to be from DayOfWeek in Java8. Looking at the Java8 javadoc for the [compareTo method in Enum](http://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html#compareTo-E-) it looks like the order will be the order in which the values are declared, which is in alphabetical order in your example. – Dan Temple May 23 '14 at 12:02
  • 1
    @AbimaranKugathasan OP's asking about why the javadoc tool produces documentation for declared enum values in alphabetical order instead of the order they were declared, and if this behavior can be altered. – awksp May 23 '14 at 12:24
  • Not only Enums, all the fields, methods are order by alphabetically. – Abimaran Kugathasan May 23 '14 at 12:26
  • @DanTemple The values in `DayOfWeek` are declared in order from Monday to Sunday though. I'm not sure that the javadoc tool uses the `compareTo()` method internally to order its output, and in this case it doesn't appear that's what is happening. – awksp May 23 '14 at 12:26
  • @user3580294 You're right, I've just looked at the code for them too. This really is a fun question. I'm guessing the answers lies deep within the [Javadoc Tool.](http://www.oracle.com/technetwork/java/javase/documentation/index.html) – Dan Temple May 23 '14 at 12:54
  • Having read [this post](http://stackoverflow.com/a/13345058/2508646) I've just seen this: `There is no standard mechanism to replace the Javadoc of a method whose source code you don't control, but you could probably mess around with either the build tool, or, if all else fails, the final Javadoc HTML.` – Dan Temple May 23 '14 at 13:01
  • @DanTemple, I've used `java.time.DayOfWeek` just as an illustration. I'm actually really interested in changing the javadoc of my own classes. – bruno May 23 '14 at 13:15
  • As ggovan just added in his answer, I was just about to mention the possibility of a customer [Doclet](http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html) – Dan Temple May 23 '14 at 13:54
  • Given the example doc which could really regarded typical, I would rather ask whether we could get rid of this “summary” part which consumes almost as much space as the detail part (which shows the items in declaration order)… – Holger May 23 '14 at 15:29

1 Answers1

1

The default HTML doclet sorts the summaries of its members.

Collections.sort(members);

from /com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java :312

It is probably best that you don't do this.

Javadoc puts the summaries in alphabetical order so that you can quickly find the one you want. Breaking that model would make the Javadoc much harder to quickly scan and find what you are looking for.

Alphabetical order only applies to the summary, the full Javadoc will be in the order of decleration in the source file.

If you really needed to do this then you could roll your own doclet or perhaps a taglet might be able to do it.

ggovan
  • 1,907
  • 18
  • 21
  • 1
    A reference for "you can't" would turn this into a valuable answer. – bruno May 23 '14 at 13:16
  • @bruno Can't find a reference for _you can't_, would probably have to look at the source to prove it. But there exist no documented mechanism for chaging the ordering of things in the summary that either of us can find. – ggovan May 23 '14 at 13:52
  • What's the basis for "*The default HTML doclet can't do this*"? The fact that either of us can find a way to make it do it? – bruno May 23 '14 at 19:10
  • @bruno It can be hard to find evidence that a non-existent feature doesn't exist. After checking the Javadoc man page, the Oracle documentation, the javadoc-dev mailing list, and SO itself and finding nothing I've done as threatened and grabbed the source to prove it. I hope that this satisfies you. – ggovan May 23 '14 at 21:35
  • Nice. I was upset that it's in alphabetical order until you told me that it's only in the summary. Now I think that the default behaviour makes perfect sense, show in alphabetical order for easy finding, like an index, and in declaration order in the details, for context. – TalL Mar 08 '20 at 09:52