Questions tagged [javadocs]
The javadocs tag has no summary.
23 questions
1
vote
2
answers
558
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
115
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
199
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
611
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
267
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
378
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
173
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
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 ...
- 217
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
891
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
1
vote
1
answer
627
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 ...
- 369
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 ...
- 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 {
/**
* ...
- 1,550
2
votes
3
answers
192
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 ...
- 161
1
vote
2
answers
229
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, ...
- 586
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
12
votes
3
answers
3k
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 ...
- 223
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 ...
- 14k
5
votes
3
answers
615
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 ...
- 575
10
votes
2
answers
3k
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?
- 839
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