Fix Javadoc issues (#657)

src/main/java/org/joda/time/DateMidnight.java

@@ -134,6 +134,7 @@ public static DateMidnight now(Chronology chronology) {
      * This uses {@link ISODateTimeFormat#dateTimeParser()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed date-midnight, not null
      * @since 2.0
      */
     @FromString
@@ -146,6 +147,7 @@ public static DateMidnight parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed date-midnight, not null
      * @since 2.0
      */
     public static DateMidnight parse(String str, DateTimeFormatter formatter) {

src/main/java/org/joda/time/DateTime.java

@@ -142,6 +142,7 @@ public static DateTime now(Chronology chronology) {
      * The object produced via the constructor has a zone of {@code DateTimeZone.getDefault()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed date-time, not null
      * @since 2.0
      */
     @FromString
@@ -154,6 +155,7 @@ public static DateTime parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed date-time, not null
      * @since 2.0
      */
     public static DateTime parse(String str, DateTimeFormatter formatter) {

src/main/java/org/joda/time/DateTimeZone.java

@@ -1235,6 +1235,7 @@ public String toString() {
      * referring to the id is written out. When the stub is read in, it
      * replaces itself with a DateTimeZone object.
      * @return a stub object to go in the stream
+     * @throws ObjectStreamException if the stream is invalid
      */
     protected Object writeReplace() throws ObjectStreamException {
         return new Stub(iID);

src/main/java/org/joda/time/Duration.java

@@ -54,6 +54,7 @@ public final class Duration
      * This parses the format {@code PTa.bS}, as per {@link #toString()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed duration, not null
      * @since 2.0
      */
     @FromString

src/main/java/org/joda/time/IllegalFieldValueException.java

@@ -340,6 +340,8 @@ public String getMessage() {
     /**
      * Provide additional detail by prepending a message to the existing message.
      * A colon is separator is automatically inserted between the messages.
+     * 
+     * @param message the message to prepend
      * @since 1.3
      */
     public void prependMessage(String message) {

src/main/java/org/joda/time/Instant.java

@@ -84,6 +84,7 @@ public static Instant now() {
      * Obtains an {@code Instant} set to the milliseconds from 1970-01-01T00:00:00Z.
      * 
      * @param epochMilli  the milliseconds from 1970-01-01T00:00:00Z
+     * @return the instant, not null
      * @since 2.10
      */
     public static Instant ofEpochMilli(long epochMilli) {
@@ -95,6 +96,7 @@ public static Instant ofEpochMilli(long epochMilli) {
      * 
      * @param epochSecond  the seconds from 1970-01-01T00:00:00Z
      * @throws ArithmeticException if the new instant exceeds the capacity of a long
+     * @return the instant, not null
      * @since 2.10
      */
     public static Instant ofEpochSecond(long epochSecond) {
@@ -108,6 +110,7 @@ public static Instant ofEpochSecond(long epochSecond) {
      * This uses {@link ISODateTimeFormat#dateTimeParser()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed instant, not null
      * @since 2.0
      */
     @FromString
@@ -120,6 +123,7 @@ public static Instant parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed instant, not null
      * @since 2.0
      */
     public static Instant parse(String str, DateTimeFormatter formatter) {

src/main/java/org/joda/time/Interval.java

@@ -69,6 +69,7 @@ public final class Interval
      * offset of the default time-zone. See also {@link #parseWithOffset(String)}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed interval, not null
      * @since 2.0
      */
     public static Interval parse(String str) {
@@ -99,6 +100,7 @@ public static Interval parse(String str) {
      * The object produced via the constructor has a zone of {@code DateTimeZone.getDefault()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed interval, not null
      * @since 2.9
      */
     public static Interval parseWithOffset(String str) {

src/main/java/org/joda/time/LocalDate.java

@@ -161,6 +161,7 @@ public static LocalDate now(Chronology chronology) {
      * This uses {@link ISODateTimeFormat#localDateParser()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed date, not null
      * @since 2.0
      */
     @FromString
@@ -173,6 +174,7 @@ public static LocalDate parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed date, not null
      * @since 2.0
      */
     public static LocalDate parse(String str, DateTimeFormatter formatter) {
@@ -1844,6 +1846,7 @@ public String toString() {
      * Output the date using the specified format pattern.
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
+     * @return the formatted output
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern) {
@@ -1858,6 +1861,8 @@ public String toString(String pattern) {
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
      * @param locale  Locale to use, null means default
+     * @return the formatted output
+     * @throws IllegalArgumentException if the pattern is invalid
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern, Locale locale) throws IllegalArgumentException {

src/main/java/org/joda/time/LocalDateTime.java

@@ -150,6 +150,7 @@ public static LocalDateTime now(Chronology chronology) {
      * This uses {@link ISODateTimeFormat#localDateOptionalTimeParser()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed date-time, not null
      * @since 2.0
      */
     @FromString
@@ -162,6 +163,7 @@ public static LocalDateTime parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed date-time, not null
      * @since 2.0
      */
     public static LocalDateTime parse(String str, DateTimeFormatter formatter) {
@@ -838,6 +840,7 @@ public Date toDate() {
      * time zone initialization logic, and should demonstrate better concurrent performance
      * characteristics.
      *
+     * @param timeZone  the time zone
      * @return a Date initialised with this date-time, never null
      * @since 2.3
      */
@@ -2113,6 +2116,7 @@ public String toString() {
      * Output the date using the specified format pattern.
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
+     * @return the formatted output, not null
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern) {
@@ -2127,6 +2131,8 @@ public String toString(String pattern) {
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
      * @param locale  Locale to use, null means default
+     * @return the formatted output, not null
+     * @throws IllegalArgumentException if the pattern is invalid
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern, Locale locale) throws IllegalArgumentException {

src/main/java/org/joda/time/LocalTime.java

@@ -157,6 +157,7 @@ public static LocalTime now(Chronology chronology) {
      * This uses {@link ISODateTimeFormat#localTimeParser()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed time, not null
      * @since 2.0
      */
     @FromString
@@ -169,6 +170,7 @@ public static LocalTime parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed time, not null
      * @since 2.0
      */
     public static LocalTime parse(String str, DateTimeFormatter formatter) {
@@ -185,6 +187,7 @@ public static LocalTime parse(String str, DateTimeFormatter formatter) {
      * This method uses the UTC time zone internally.
      *
      * @param millisOfDay  the number of milliseconds into a day to convert
+     * @return the time, not null
      */
     public static LocalTime fromMillisOfDay(long millisOfDay) {
         return fromMillisOfDay(millisOfDay, null);
@@ -200,6 +203,7 @@ public static LocalTime fromMillisOfDay(long millisOfDay) {
      *
      * @param millisOfDay  the number of milliseconds into a day to convert
      * @param chrono  the chronology, null means ISO chronology
+     * @return the time, not null
      */
     public static LocalTime fromMillisOfDay(long millisOfDay, Chronology chrono) {
         chrono = DateTimeUtils.getChronology(chrono).withUTC();
@@ -1325,6 +1329,7 @@ public String toString() {
      * Output the time using the specified format pattern.
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
+     * @return the formatted output, not null
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern) {
@@ -1339,6 +1344,8 @@ public String toString(String pattern) {
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
      * @param locale  Locale to use, null means default
+     * @return the formatted output, not null
+     * @throws IllegalArgumentException if the pattern is invalid
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern, Locale locale) throws IllegalArgumentException {

src/main/java/org/joda/time/MonthDay.java

@@ -142,6 +142,7 @@ public static MonthDay now(Chronology chronology) {
      * This uses {@link ISODateTimeFormat#localDateParser()} or the format {@code --MM-dd}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed month-day, not null
      * @since 2.0
      */
     @FromString
@@ -154,6 +155,7 @@ public static MonthDay parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed month-day, not null
      * @since 2.0
      */
     public static MonthDay parse(String str, DateTimeFormatter formatter) {

src/main/java/org/joda/time/MutableDateTime.java

@@ -142,6 +142,7 @@ public static MutableDateTime now(Chronology chronology) {
      * This uses {@link ISODateTimeFormat#dateTimeParser()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed date-time, not null
      * @since 2.0
      */
     @FromString
@@ -154,6 +155,7 @@ public static MutableDateTime parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed date-time, not null
      * @since 2.0
      */
     public static MutableDateTime parse(String str, DateTimeFormatter formatter) {

src/main/java/org/joda/time/MutableInterval.java

@@ -65,6 +65,7 @@ public class MutableInterval
      * 'datetime/period' or 'period/datetime'.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed interval, not null
      * @since 2.0
      */
     public static MutableInterval parse(String str) {

src/main/java/org/joda/time/MutablePeriod.java

@@ -67,6 +67,7 @@ public class MutablePeriod
      * This uses {@link ISOPeriodFormat#standard()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed period, not null
      * @since 2.0
      */
     @FromString
@@ -79,6 +80,7 @@ public static MutablePeriod parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed period, not null
      * @since 2.0
      */
     public static MutablePeriod parse(String str, PeriodFormatter formatter) {

src/main/java/org/joda/time/Partial.java

@@ -278,6 +278,8 @@ public Partial(DateTimeFieldType[] types, int[] values, Chronology chronology) {
      * another partial.
      * <p>
      * This is most useful when copying from a YearMonthDay or TimeOfDay.
+     * 
+     * @param partial  the partial to copy
      */
     public Partial(ReadablePartial partial) {
         super();
@@ -816,6 +818,7 @@ public String toStringList() {
      * Unsupported fields will appear as special unicode characters.
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
+     * @return the formatted output, not null
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern) {
@@ -831,6 +834,7 @@ public String toString(String pattern) {
      *
      * @param pattern  the pattern specification, null means use <code>toString</code>
      * @param locale  Locale to use, null means default
+     * @return the formatted output, not null
      * @see org.joda.time.format.DateTimeFormat
      */
     public String toString(String pattern, Locale locale) {

src/main/java/org/joda/time/Period.java

@@ -74,6 +74,7 @@ public final class Period
      * This uses {@link ISOPeriodFormat#standard()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed period, not null
      * @since 2.0
      */
     @FromString
@@ -86,6 +87,7 @@ public static Period parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed period, not null
      * @since 2.0
      */
     public static Period parse(String str, PeriodFormatter formatter) {
@@ -250,6 +252,7 @@ public static Period millis(int millis) {
      *
      * @param start  the start of the period, must not be null
      * @param end  the end of the period, must not be null
+     * @return the period, not null
      * @throws IllegalArgumentException if the partials are null or invalid
      * @since 1.1
      */

src/main/java/org/joda/time/ReadableDateTime.java

@@ -195,6 +195,7 @@ public interface ReadableDateTime extends ReadableInstant {
      * Output the instant using the specified format pattern.
      *
      * @param pattern  pattern specification
+     * @return the formatted output, not null
      * @throws IllegalArgumentException  if pattern is invalid
      * @see  org.joda.time.format.DateTimeFormat
      */
@@ -205,6 +206,7 @@ public interface ReadableDateTime extends ReadableInstant {
      *
      * @param pattern  pattern specification
      * @param locale  Locale to use, or null for default
+     * @return the formatted output, not null
      * @throws IllegalArgumentException  if pattern is invalid
      * @see  org.joda.time.format.DateTimeFormat
      */

src/main/java/org/joda/time/ReadableInstant.java

@@ -145,7 +145,7 @@ public interface ReadableInstant extends Comparable<ReadableInstant> {
      * <p>
      * To compare two instants for absolute time (ie. UTC milliseconds 
      * ignoring the chronology), use {@link #isEqual(ReadableInstant)} or
-     * {@link #compareTo(Object)}.
+     * {@link #compareTo}.
      *
      * @param readableInstant  a readable instant to check against
      * @return true if millisecond and chronology are equal, false if

src/main/java/org/joda/time/TimeOfDay.java

@@ -163,6 +163,7 @@ public static TimeOfDay fromDateFields(Date date) {
      * This method uses the UTC time zone internally.
      *
      * @param millisOfDay  the number of milliseconds into a day to convert
+     * @return the time, not null
      */
     public static TimeOfDay fromMillisOfDay(long millisOfDay) {
         return fromMillisOfDay(millisOfDay, null);
@@ -178,6 +179,7 @@ public static TimeOfDay fromMillisOfDay(long millisOfDay) {
      *
      * @param millisOfDay  the number of milliseconds into a day to convert
      * @param chrono  the chronology, null means ISO chronology
+     * @return the time, not null
      */
     public static TimeOfDay fromMillisOfDay(long millisOfDay, Chronology chrono) {
         chrono = DateTimeUtils.getChronology(chrono);

src/main/java/org/joda/time/YearMonth.java

@@ -134,6 +134,7 @@ public static YearMonth now(Chronology chronology) {
      * This uses {@link ISODateTimeFormat#localDateParser()}.
      * 
      * @param str  the string to parse, not null
+     * @return the parsed year-month, not null
      * @since 2.0
      */
     @FromString
@@ -146,6 +147,7 @@ public static YearMonth parse(String str) {
      * 
      * @param str  the string to parse, not null
      * @param formatter  the formatter to use, not null
+     * @return the parsed year-month, not null
      * @since 2.0
      */
     public static YearMonth parse(String str, DateTimeFormatter formatter) {