The tag has no wiki summary.

learn more… | top users | synonyms

0
votes
1answer
39 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. */ ...
0
votes
4answers
200 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. ...
0
votes
1answer
134 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 ...
2
votes
1answer
586 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 ...
1
vote
2answers
172 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 { /** * ...
2
votes
3answers
149 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 ...
1
vote
2answers
130 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 ...
8
votes
2answers
657 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 ...
3
votes
1answer
302 views

Different ways of managing Java code documentation

What are good alternatives 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, so ...
2
votes
1answer
510 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 ...
8
votes
3answers
172 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 ...
5
votes
1answer
564 views

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 ...
4
votes
3answers
203 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 ...
7
votes
2answers
596 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?
12
votes
6answers
2k 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 ...