We Keep Coding

Is it possible to override a method comment but not the method?

I have methods toSaveString(StringBuilder) and toSaveString() in several classes and thought of turning those into an interface. The first method would always have to be implemented and the second I could default because it basically only calls the first method every time with a new string builder and returns the resulting string. (Not what default is designed for, but bear with me.)
Now I wouldn't need to implement toSaveString() in the classes implementing the interface, but I would like to change its documentation nonetheless to match the class. Is there a way to achieve this without overriding the toSaveString() method in the implementing class? Because adding three lines to call the default method or five to copy the implementation seems redundant and easy to get errors mixed in.
Also feel free to leave comments about design alternatives here, but the question stays because it is interesting in its own right.

Look at the javadoc of the ArrayList#removeIf method:
/**
* #throws NullPointerException {#inheritDoc}
*/
#Override
public boolean removeIf(Predicate<? super E> filter) {
return removeIf(filter, 0, size);
}
It overrides its superclass Collection#removeIf method:
/**
* Removes all of the elements of this collection that satisfy the given
* predicate. Errors or runtime exceptions thrown during iteration or by
* the predicate are relayed to the caller.
*
* #implSpec
* The default implementation traverses all elements of the collection using
* its {#link #iterator}. Each matching element is removed using
* {#link Iterator#remove()}. If the collection's iterator does not
* support removal then an {#code UnsupportedOperationException} will be
* thrown on the first matching element.
*
* #param filter a predicate which returns {#code true} for elements to be
* removed
* #return {#code true} if any elements were removed
* #throws NullPointerException if the specified filter is null
* #throws UnsupportedOperationException if elements cannot be removed
* from this collection. Implementations may throw this exception if a
* matching element cannot be removed or if, in general, removal is not
* supported.
* #since 1.8
*/
default boolean removeIf(Predicate<? super E> filter) {
Objects.requireNonNull(filter);
boolean removed = false;
final Iterator<E> each = iterator();
while (each.hasNext()) {
if (filter.test(each.next())) {
each.remove();
removed = true;
}
}
return removed;
}
In your case, you can override only javadoc, and write something like this in the method body:
/**
* custom javadoc
*/
#Override
public boolean customMethod(Object parameter) {
return super.customMethod(parameter);
}
See also: Can I add code to an inherited method without overriding the whole method?

How to write Javadoc for a getInstance method?

Say I have something like this:
public class MyClass {
private static MyClass sInstance;
/**
*
* #return The {#link MyClass} application instance.
*/
public static MyClass getInstance() {
return sInstance;
}
}
IntelliJ gives me this warning:
'#link' pointing to containing class is unnecessary
What's the proper/conventional way to write this piece of Javadoc?
How would you write it?

In the JDK, they use {#code}. That does not make a clickable link, but you are already looking at the page that would be linked anyway.
For example (from String.java):
/**
* Initializes a newly created {#code String} object so that it represents
* the same sequence of characters as the argument; in other words, the
* newly created string is a copy of the argument string. Unless an
* explicit copy of {#code original} is needed, use of this constructor is
* unnecessary since Strings are immutable.
*
* #param original
* A {#code String}
*/

You only get the warning because the link won't go anywhere. Just change it to {#code MyClass} to keep the formatting but without the link.
Here are some example getInstance() methods from the JDK.
java.text.Collator:
/**
* Gets the Collator for the current default locale.
* The default locale is determined by java.util.Locale.getDefault.
* #return the Collator for the default locale.(for example, en_US)
* #see java.util.Locale#getDefault
*/
public static synchronized Collator getInstance() {
java.text.NumberFormat:
/**
* Returns a general-purpose number format for the current default
* {#link java.util.Locale.Category#FORMAT FORMAT} locale.
* This is the same as calling
* {#link #getNumberInstance() getNumberInstance()}.
*
* #return the {#code NumberFormat} instance for general-purpose number
* formatting
*/
public final static NumberFormat getInstance() {

Why A.class is null in run time?

I meet a problem when using A.class in program and it return java.lang.NullPointerException at run-time
This is my snipped code:
public synchronized boolean isDeviceEqual(IDevice dev) {
............
if( isDeviceInstanceOf(SimpleDevice.class) ) {
return dev instanceof IDevice
&& XXX();
}
............
}
public boolean isDeviceInstanceOf(Class cls) {
return cls.isAssignableFrom(mDeviceClass);
}
and NPE
java.lang.NullPointerException
at xxx/library/DeviceDescriptor.isDeviceInstanceOf(Ljava/lang/Class;)Z (:0:5)
at xxx/library/DeviceDescriptor.isDeviceEqual(LIDevice;)Z (:0:6)
with above NPE, it means that cls is null in this case but I can't explain why this happens so can anybody help me?

cls.isAssignableFrom(mDeviceClass) will throw a NullPointerException if mDeviceClass, which must be the case here, since you are sure that cls is not null.
/**
* Determines if the class or interface represented by this
* <code>Class</code> object is either the same as, or is a superclass or
* superinterface of, the class or interface represented by the specified
* <code>Class</code> parameter. It returns <code>true</code> if so;
* otherwise it returns <code>false</code>. If this <code>Class</code>
* object represents a primitive type, this method returns
* <code>true</code> if the specified <code>Class</code> parameter is
* exactly this <code>Class</code> object; otherwise it returns
* <code>false</code>.
*
* <p> Specifically, this method tests whether the type represented by the
* specified <code>Class</code> parameter can be converted to the type
* represented by this <code>Class</code> object via an identity conversion
* or via a widening reference conversion. See <em>The Java Language
* Specification</em>, sections 5.1.1 and 5.1.4 , for details.
*
* #param cls the <code>Class</code> object to be checked
* #return the <code>boolean</code> value indicating whether objects of the
* type <code>cls</code> can be assigned to objects of this class
* #exception NullPointerException if the specified Class parameter is
* null.
* #since JDK1.1
*/
public native boolean isAssignableFrom(Class<?> cls);
It seems strange that in isDeviceEqual(IDevice dev) you are not doing anything with dev. I don't know what mDeviceClass is, but perhaps it should be assigned dev.getClass() somewhere.

How to keep track of non empty field in Joda date buffer

I'm writing a set of objects that should be able to alter fields in a Joda Time MutableDateTime instance.
Each object is applied in sequence to the buffer, and when all that set is applied, a complete valid MutableDateTime will be built.
Each instance have to be able to know which date time fields has already been set by other instances in the set.
I get stucked because I get following problems:
How to create the MutableDateTime instance with empty values in all
date time fields in order to use it as the initial value to build?
How could I know if some field of MutableDateTime has been set?
MutableDateTime internally keep track it's data in a long instance field initialized to number of milliseconds elapsed from start of era to now. It thus has all field already set to some value.
Do you know if MutableDateTime has some concept of an empty value?
Edit:
as I show in my response, I develop a solution using a manager class as Vladimir suggested.

You should create "Manager" class to remember fields which was already set. It should throw exception if user tries to retrieve instance of MutableDateTime before all fields was set.
And if you always set all fields for MutableDateTime then [1] is not important (values will be overwriten).

I finally changed my initial design, and I implemented it exactly as Vadim Ponomarev suggested. Since each field type in Joda buffer has a corresponding DateTimeFieldType instance, I use a private Set object to keep track of the fields present.
The code below show how I've done:
private final Set<DateTimeFieldType> fieldTypes = Sets.newHashSet();
/**
* Allow to set to or reset one of the DateTimeFieldType fields
* #param fieldType the DateTimeFieldType field to change
* #param value the value to set it
*/
public void changeField(DateTimeFieldType fieldType, boolean value) {
if (value)
fieldTypes.add(fieldType);
else
fieldTypes.remove(fieldType);
}
/**
* Check if one of the DateTimeFieldType is present in this set.
* #param fieldType The field type to check for presence.
* #return true if the DateTimeFieldType is present, otherwise false
*/
public boolean isFieldSet(DateTimeFieldType fieldType) {
return !fieldTypes.contains(fieldType);
}
I've also added some utility methods allowing to change all fields for the date and all fields for the time at once. This could be useful in client to code to easy a common operation on date field sets.
/**
* Allow to set the fields that build the time part
* of a date time
* <p/>
*
* #param value value to set the DateTime fields
*/
public void changeTimeFields(boolean value) {
changeField(DateTimeFieldType.hourOfDay(), value);
changeField(DateTimeFieldType.minuteOfHour(), value);
}
/**
* Allow to set the fields that build the date part
* of a date time
* <p/>
*
* #param value value to set the DateTime fields
*/
public void changeDateFields(boolean value) {
changeField(DateTimeFieldType.dayOfMonth(), value);
changeField(DateTimeFieldType.monthOfYear(), value);
changeField(DateTimeFieldType.yearOfEra(), value);
}
And finally, I also added some method to query if all date fields are set and if all time fields are set:
/**
* Allow to check if the DateTimeFieldType fields that build the
* date part of a datetime has been set in this instance.
* <p/>
*
* #return true if date part has yet to be applied to
* the instance, false otherwise
*/
public boolean isDateSet() {
return fieldTypes.contains(DateTimeFieldType.dayOfMonth()) &&
fieldTypes.contains(DateTimeFieldType.monthOfYear()) &&
fieldTypes.contains(DateTimeFieldType.yearOfEra());
}
/**
* Allow to check if the DateTimeFieldType fields that build the
* time part of a datetime has been set in this instance.
* <p/>
*
* #return true if time part has yet to be applied to
* the instance, false otherwise
*/
public boolean isTimeSet() {
return fieldTypes.contains(DateTimeFieldType.minuteOfHour()) &&
fieldTypes.contains(DateTimeFieldType.hourOfDay());
}
I finally made it a DateTimeFieldTypeSet class. I think it encapsulate well a common concept that is lacking in Joda classes. I hope it can be useful to some one else too.

eclipse add unimplemented methods including javadoc

When implementing an interface in eclipse, it has a really nice feature that lets you "add unimplemented methods", and it will generate the method stubs for the interface methods.
However, it does not bring along the method documentation from the interface methods, and I was wondering if there was a way to get eclipse to do that.
Here's what I want to happen. Let's say I had an interface like this:
public interface BaseInterface {
/**
* This method takes the given string parameter and returns its integer value.
*
* #param x the string to convert
* #return the integer value of the string
*
* #throws Exception if some error occurs
*/
int method1(String x);
}
Now I create a class called MyClass which implements this interface. What I want to happen is that when I say "Add Unimplemented Methods", I want my code to look like this:
public class MyClass implements BaseInterface {
/**
* This method takes the given string parameter and returns its integer value.
*
* #param x the string to convert
* #return the integer value of the string
*
* #throws Exception if some error occurs
*/
public int method1(String x) {
return 0;
}
}

Yup : these methods are generated using the code templates you wrote.
You'll have to go in "Window/Preferences -> Java/Code style/Code templates"
Then, in the list, select "Comments/overriding methods" and change the content with the one you found in "Comments/methods" :
/**
* ${tags}
*/
You can even think about adding an ${see_to_overridden} to have a direct link to original method. However, notice that a method with no javadoc will automatically inherit its javadoc from its overriden one, so such a template may generate less relevant doc than default behaviour.

You can achieve it by JavaDoc annotation. It is not Eclipse specific and will work in all build/doc generation tools:
/**
* My custom decumentation, and then the original one:
*
* {#inheritDoc}
*/