All Questions
15 questions
1
vote
2
answers
497
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 ...
- 113
-4
votes
1
answer
108
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?
-2
votes
1
answer
184
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 ...
- 101
-2
votes
1
answer
591
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, ...
- 419
2
votes
1
answer
251
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. ...
- 131
9
votes
1
answer
366
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 ...
- 273
1
vote
1
answer
160
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 ...
- 651
10
votes
1
answer
33k
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.
*/ ...
- 325
2
votes
4
answers
867
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'd ...
- 153
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 {
/**
* ...
- 1,550
1
vote
2
answers
188
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 ...
- 121
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, ...
- 596
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.
- 1,100
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 ...
- 37
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....
- 1,773