Questions tagged [javadocs]
The javadocs tag has no summary.
23 questions
1 vote
2 answers
561 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
175 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
628 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