Fix javadoc warnings

.gitignore

@@ -15,3 +15,4 @@ target/
 /*.iws
 out
 .gradletasknamecache
+.DS_Store

src/main/java/org/springframework/shell/TerminalSizeAware.java

@@ -1,9 +1,25 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.springframework.shell;
 
 /**
  * To be implemented by command result objects that can adapt to the terminal size when they are being rendered.
  *
- * <p>An object which does not implement this interface will simply be rendered by invoking its {@link #toString()}
+ * <p>An object which does not implement this interface will simply be rendered by invoking its {@link Object#toString()}
  * method.</p>
  *
  * @author Eric Bottard

src/main/java/org/springframework/shell/table/Aligner.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,11 +24,18 @@ package org.springframework.shell.table;
 public interface Aligner {
 
 	/**
-	 * Perform text alignment, returning a String array that MUST contain
+	 * Perform text alignment, returning a String array that MUST contain {@code cellHeight}
-	 * {@code cellHeight} lines, each of which MUST be {@code cellWidth} chars in length.
+	 * lines, each of which MUST be {@code cellWidth} chars in length.
 	 *
-	 * <p>Input array is guaranteed to contain lines that have length equal to {@cellWidth}. There
+	 * <p>
-	 * is no guarantee on the input number of lines though.</p>
+	 * Input array is guaranteed to contain lines that have length equal to {@code cellWidth}.
+	 * There is no guarantee on the input number of lines though.
+	 * </p>
+	 * 
+	 * @param text the text to align
+	 * @param cellWidth the width of of the table cell
+	 * @param cellHeight the height of the table cell
+	 * @return the aligned text, in a {@code cellHeight} element array
 	 */
 	String[] align(String[] text, int cellWidth, int cellHeight);
 }

src/main/java/org/springframework/shell/table/CellMatcher.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,7 +26,10 @@ package org.springframework.shell.table;
 public interface CellMatcher {
 
 	/**
-	 * Return whether a given cell of the table should match.
+	 * @return whether a given cell of the table should match.
+	 * @param row the row being tested.
+	 * @param column the column being tested
+	 * @param model the data model of the table
 	 */
 	public boolean matches(int row, int column, TableModel model);
 }

src/main/java/org/springframework/shell/table/CellMatchers.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ package org.springframework.shell.table;
 public class CellMatchers {
 
 	/**
-	 * Return a matcher that applies to every cell of the table.
+	 * @return a matcher that applies to every cell of the table.
 	 */
 	public static CellMatcher table() {
 		return new CellMatcher() {
@@ -35,7 +35,8 @@ public class CellMatchers {
 	}
 
 	/**
-	 * Return a matcher that applies to every cell of some column of the table.
+	 * @return a matcher that applies to every cell of some column of the table.
+	 * @param col the column to select
 	 */
 	public static CellMatcher column(final int col) {
 		return new CellMatcher() {
@@ -46,7 +47,8 @@ public class CellMatchers {
 	}
 
 	/**
-	 * Return a matcher that applies to every cell of some row of the table.
+	 * @return a matcher that applies to every cell of some row of the table.
+	 * @param theRow the row to select
 	 */
 	public static CellMatcher row(final int theRow) {
 		return new CellMatcher() {
@@ -56,6 +58,10 @@ public class CellMatchers {
 		};
 	}
 
+	/**
+	 * @param clazz the type that cells should contain
+	 * @return a matcher that matches cells whose content is of a certain type
+	 */
 	public static CellMatcher ofType(final Class<?> clazz) {
 		return new CellMatcher() {
 			@Override

src/main/java/org/springframework/shell/table/SizeConstraints.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@ import org.springframework.util.Assert;
 public interface SizeConstraints {
 
 	/**
-	 * Return the minimum and maximum width of the cell, given its raw content.
+	 * @return the minimum and maximum width of the cell, given its raw content.
 	 * @param raw the raw String representation of the cell contents (may be reformatted later, eg wrapped)
 	 * @param tableWidth the whole available width for the table
 	 * @param nbColumns the number of columns in the table

src/main/java/org/springframework/shell/table/Table.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,14 +30,14 @@ import org.springframework.shell.TerminalSizeAware;
  * TableModel, which holds raw table contents. Its rendering logic is then altered by applying
  * various customizations, in a fashion very similar to what is used <i>e.g.</i> in a spreadsheet
  * program:<ol>
- * <li>{@link #format(CellMatcher, Formatter) formatters} know how to derive character data out of raw data. For
+ * <li>{@link #formatters formatters} know how to derive character data out of raw data. For
  * example, numbers are
  * formatted according to a Locale, or Maps are emitted as a series of {@literal key=value} lines</li>
- * <li>{@link #size(CellMatcher, SizeConstraints) size constraints} are then applied, which decide how
+ * <li>{@link #sizeConstraints size constraints} are then applied, which decide how
  * much column real estate to allocate to cells</li>
- * <li>{@link #wrap(CellMatcher, TextWrapper) text wrapping policies} are applied once the column sizes
+ * <li>{@link #wrappers text wrapping policies} are applied once the column sizes
  * are known</li>
- * <li>finally, {@link #align(CellMatcher, Aligner) alignment} strategies actually render
+ * <li>finally, {@link #aligners alignment} strategies actually render
  * text as a series of space-padded strings that draw nicely on screen.</li>
  * </ol>
  * All those customizations are applied selectively on the Table cells thanks to a {@link CellMatcher}: One can

src/main/java/org/springframework/shell/table/TableBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -60,6 +60,8 @@ public class TableBuilder {
 	 * <li>{@link DelimiterTextWrapper wrapping text} on space characters</li>
 	 * <li>{@link SimpleHorizontalAligner left aligning} text.</li>
 	 * </ul>
+	 *
+	 * @param model the data model of the table to construct
 	 */
 
 	public TableBuilder(TableModel model) {
@@ -109,6 +111,8 @@ public class TableBuilder {
 
 	/**
 	 * Set a border on the outline of the whole table.
+	 * @param style the style to apply
+	 * @return this, for method chaining
 	 */
 	public TableBuilder addOutlineBorder(BorderStyle style) {
 		this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), OUTLINE, style);
@@ -117,6 +121,8 @@ public class TableBuilder {
 
 	/**
 	 * Set a border on the outline of the whole table, as well as around the first row.
+	 * @param style the style to apply
+	 * @return this, for method chaining
 	 */
 	public TableBuilder addHeaderBorder(BorderStyle style) {
 		this.addBorder(0, 0, 1, model.getColumnCount(), OUTLINE, style);
@@ -125,6 +131,9 @@ public class TableBuilder {
 
 	/**
 	 * Set a border around each and every cell of the table.
+	 *
+	 * @param style the style to apply
+	 * @return this, for method chaining
 	 */
 	public TableBuilder addFullBorder(BorderStyle style) {
 		this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), FULL, style);
@@ -134,6 +143,9 @@ public class TableBuilder {
 	/**
 	 * Set a border on the outline of the whole table, around the first row and draw vertical lines
 	 * around each column.
+	 *
+	 * @param style the style to apply
+	 * @return this, for method chaining
 	 */
 	public TableBuilder addHeaderAndVerticalsBorders(BorderStyle style) {
 		this.addBorder(0, 0, 1, model.getColumnCount(), OUTLINE, style);
@@ -143,6 +155,9 @@ public class TableBuilder {
 
 	/**
 	 * Set a border on the inner verticals and horizontals of the table, but not on the outline.
+	 *
+	 * @param style the style to apply
+	 * @return this, for method chaining
 	 */
 	public TableBuilder addInnerBorder(BorderStyle style) {
 		this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), INNER, style);

src/main/java/org/springframework/shell/table/TableModel.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,24 +24,26 @@ package org.springframework.shell.table;
 public abstract class TableModel {
 
 	/**
-	 * Return the number of rows that can be queried.
+	 * @return the number of rows that can be queried.
 	 * Values between 0 and {@code rowCount-1} inclusive are valid values.
 	 */
 	public abstract int getRowCount();
 
 	/**
-	 * Return the number of columns that can be queried.
+	 * @return the number of columns that can be queried.
 	 * Values between 0 and {@code columnCount-1} inclusive are valid values.
 	 */
 	public abstract int getColumnCount();
 
 	/**
-	 * Return the data value to be displayed at a given row and column, which may be null.
+	 * @return the data value to be displayed at a given row and column, which may be null.
+	 * @param row the row that is being queried
+	 * @param column the column that is being queried
 	 */
 	public abstract Object getValue(int row, int column);
 
 	/**
-	 * Return a transposed view of this model, where rows become columns and vice-versa.
+	 * @return a transposed view of this model, where rows become columns and vice-versa.
 	 */
 	public TableModel transpose() {
 		return new TableModel() {

src/main/java/org/springframework/shell/table/Tables.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,6 +27,10 @@ public class Tables {
 
 	/**
 	 * Install all the necessary formatters, aligners, etc for key-value rendering of Maps.
+	 *
+	 * @param builder the builder to configure
+	 * @param delimiter the delimiter to apply between keys and values
+	 * @return buider for method chaining
 	 */
 	public static TableBuilder configureKeyValueRendering(TableBuilder builder, String delimiter) {
 		return builder.on(CellMatchers.ofType(Map.class))

src/main/java/org/springframework/shell/table/TextWrapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,13 +18,18 @@ package org.springframework.shell.table;
 
 /**
  * A strategy for applying text wrapping/cropping given a cell width.
+ *
+ * @author Eric Bottard
  */
 public interface TextWrapper {
 
 	/**
-	 * Return a list of lines where each line length MUST be equal to {@code columnWidth} (padding with spaces if
+	 * @return a list of lines where each line length MUST be equal to {@code columnWidth} (padding with spaces if
 	 * appropriate). There is no constraint on the number of lines returned however (typically, will be greater than
 	 * the input number if wrapping occurred).
+	 *
+	 * @param original the text in its original form
+	 * @param columnWidth the width to conform to
 	 */
 	String[] wrap(String[] original, int columnWidth);
 }