Questions tagged [javadocs]
23 questions
19
votes
6 answers
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.
I tend to lean on the side of thinking that…

Andreas Johansson
- 1,763
- 13
- 18
12
votes
3 answers
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 change? (Yeah, I know, those methods shouldn't be…

Michael Levy
- 223
- 1
- 6
11
votes
2 answers
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, but not Denigrated. I found a bug report about…

Jacob Schoen
- 596
- 4
- 15
10
votes
1 answer
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.
*/
private List usernames = new…

benscabbia
- 325
- 2
- 4
- 10
10
votes
2 answers
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
- 829
- 1
- 7
- 20
9
votes
1 answer
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 this I've automated most processes so I can…

M.P. Korstanje
- 263
- 2
- 8
9
votes
1 answer
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.
- 957
- 6
- 16
8
votes
3 answers
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 free to look at the code, but
when using somebody…

Todd Davies
- 217
- 1
- 7
7
votes
1 answer
Standardized code documentation format, where is it?
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 is used for Java (duh), PHP (PHPDocumentor,…

dukeofgaming
- 13,943
- 6
- 50
- 77
5
votes
3 answers
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 give myself credit as the person who ported it…

Adam Harte
- 575
- 4
- 11
3
votes
1 answer
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 interfaces. I trust my users to still implement it…

Mog
- 141
- 1
- 5
3
votes
2 answers
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 {
/**
* Starts to process the sepcified event…

SpaceTrucker
- 1,462
- 10
- 13
2
votes
1 answer
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. bigDecimal.isGreaterThan(otherBigDecimal) is easier to…

lemuel
- 131
- 2
2
votes
4 answers
When copy/pasting private methods is it necessary to carry along the Javadoc?
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 have preferred if the developers of the method…

Mitch
- 153
- 1
- 1
- 6
2
votes
3 answers
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 opinion the documentation should not only contain…

DmiN
- 161
- 1
- 5