Questions tagged [javadocs]

The tag has no usage guidance.

Filter by
Sorted by
Tagged with
1 vote
2 answers
349 views

Is using KDoc/Javadoc comments inside of a function considered bad practice?

I often find it helpful to use KDoc/Javadoc comments inside of a class or function instead of normal comments. IntelliJ colorizes them more obviously by default and, more importantly, allows ...
Matt Robertson's user avatar
-4 votes
1 answer
96 views

Will a JavaDoc and a little handwritten documentation be enough for a library? [closed]

I am wondering if I wrote a little simple documentation and provided the JavaDoc, would it be enough documentation for a application GUI manager library for java?
Sushila Jyothi Lévêque's user avatar
-2 votes
1 answer
178 views

Industry Prevalence of JML Specification

In the Java course I'm currently doing at university, a lot of emphasis is placed on using JML constructs like @require and @ensure clauses in Javadoc comments. I understand that this is implementing ...
jmcph4's user avatar
  • 101
-2 votes
1 answer
554 views

Why does Java source code contain so many single-letter variables? [closed]

I have been reading the source code of some Java library classes, specifically CompletableFuture. I noticed that the authors are making extensive use of cryptic (single-letter) variables in the code, ...
Dimos's user avatar
  • 419
2 votes
1 answer
219 views

In Java, why is there no instance method like bigDecimal.isGreaterThan(otherBigDecimal)?

The current way of knowing if a BigDecimal is greater than another is bigDecimal.compareTo(otherBigDecimal) > 0 (or one.compareTo(another) == 1), but I find it too clunky and unexpressive. ...
lemuel's user avatar
  • 131
9 votes
1 answer
360 views

How to keep code examples in javadocs up to date

I'm working on a small library that provides implementations of basic, well known string metrics. Mostly for my own education. So development happens whenever I've got a bit of spare time. Because of ...
M.P. Korstanje's user avatar
1 vote
1 answer
159 views

Method documents differs between Java docs and Android docs

Some times I see problematic differences between Java doc and Android doc in about method documents.For example in about setReadable (boolean readable, boolean ownerOnly) method you can see java doc ...
hasanghaforian's user avatar
8 votes
3 answers
1k views

Is reading javadoc preferable to reading source code to familiarise yourself with a library?

I just came across the following in a lab manual at university: You do need to study the interfaces of the classes by generating the javadoc for them so you know what operations are provided (feel ...
Todd Davies's user avatar
10 votes
1 answer
31k views

Java Doc - Do fields also get documented?

This is a really simple question but oddly, I'm finding it difficult to get a definite answer.... What do you do with fields? Is this valid? /** * Keeps track of all usernames in the system. */ ...
benscabbia's user avatar
2 votes
4 answers
833 views

When copy/pasting private methods is it necessary to carry along the Javadoc? [closed]

So, unfortunately, I'm stuck with code where I'm doing this: @Override method A{ //calls private methods 1-8 } private method 1{ //copy/pasted } And so on for all of the private methods. I'...
Mitch's user avatar
  • 153
1 vote
1 answer
597 views

How do I include Implementation and Usage Documentation in one file

There are two types of documentation. One type, the Implementation Documentation, contains information about specific implementation of a construct (eg. Class, Method, etc.). It is targeted to the ...
Angelo.Hannes's user avatar
3 votes
1 answer
3k views

Javadoc for a static "overloaded" method

My problem is the following: I have an interface that requires its implementations to implement a static method, namely void load(). However, until Java 8, it seems we won't get static methods in ...
Mog's user avatar
  • 141
3 votes
2 answers
3k views

Is repeating links to the same class in a single javadoc comment a bad practice?

I'm currently writing an API and its documentation. For example I have something like this: public interface Event { } public interface Process { } public interface EventProcessor { /** * ...
SpaceTrucker's user avatar
  • 1,512
2 votes
3 answers
179 views

Preferrable Method to record Documentation

As any taught Software Engineer knows how important Documentation for good software projects is. Could you show me best practices for assure good documentation beside of JavaDoc comments? In my ...
DmiN's user avatar
  • 161
1 vote
2 answers
181 views

@Deprecated as of version x.y in JavaDoc

This question & its answers are useful but not sufficient for my problem. My Question is if I want to add a javadoc as @Deprecated As of version x.y, replaced by {@link SomeClass} in my current ...
Soumyadip Das's user avatar
11 votes
2 answers
2k views

Deprecated vs. Denigrated in JavaDoc?

In the JavaDoc for X509Certificate getSubjectDN() it states: Denigrated, replaced by getSubjectX500Principal(). I am used to seeing Deprecated in the for methods that should not be used any longer, ...
Jacob Schoen's user avatar
9 votes
1 answer
2k views

Java code documentation in a separate docs file somehow mapped to a source file?

What would be a good alternative to inline Java documentation, i.e. can one have a separate docs file somehow mapped to a java source file? I have never liked huge comment sections littered in code.
S.D.'s user avatar
  • 1,080
2 votes
1 answer
1k views

A better JavaDoc? [closed]

The standard JavaDoc template(Doclet) didn't change much until the recent JDK7. In my opinion, JDK7 template only made it even more difficult to browse. I looked at several third-party doclets, but ...
chemhack's user avatar
12 votes
3 answers
2k views

How to document experimental or incomplete APIs like @deprecated?

Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely ...
Michael Levy's user avatar
7 votes
1 answer
2k views

Standardized code documentation format, where is it? [closed]

I'm currently looking into API documentation generation tools and I noticed that apparently there are no efforts going on in standardization. Javadoc style is kind of an ubiquitous convention... it ...
dukeofgaming's user avatar
5 votes
3 answers
574 views

Porting library, what to do with JavaDoc comments/credits

I ported a library to Java, but am wondering what to do with the JavaDoc comments. The original library used javadoc comments too, so do I leave the @author tags from the original code? And how do I ...
Adam Harte's user avatar
10 votes
2 answers
2k views

DRY way to write Javadoc on overload methods

I want to write Javadoc in DRY way. But the oracle document about Javadoc says write same thing again in overload method comment. Can't I avoid repetition?
Sanghyun Lee's user avatar
19 votes
6 answers
6k views

Self-documenting code vs Javadocs?

Recently I've been working on refactoring parts of the code base I'm currently dealing with - not only to understand it better myself, but also to make it easier for others who are working on the code....
Andreas Johansson's user avatar