Simplify adding new column to table

core/src/main/java/tech/tablesaw/analytic/AnalyticQueryEngine.java

@@ -29,6 +29,7 @@ private AnalyticQueryEngine(AnalyticQuery query) {
     this.rowComparator = sort.isPresent() ? SortUtils.getChain(query.getTable(), sort.get()) : null;
   }
 
+  /** Returns a new AnalyticQueryEngine to execute the given query */
   public static AnalyticQueryEngine create(AnalyticQuery query) {
     return new AnalyticQueryEngine(query);
   }

core/src/main/java/tech/tablesaw/analytic/FunctionMetaData.java

@@ -4,9 +4,13 @@
 
 /** Base class for an Analytic Function. */
 interface FunctionMetaData {
+
+  /** Returns the name of the function */
   String functionName();
 
+  /** Returns the type of column that will hold the return values of the function */
   ColumnType returnType();
 
+  /** Returns true if the function can be applied to data of the given {@link ColumnType} */
   boolean isCompatibleColumn(ColumnType type);
 }

core/src/main/java/tech/tablesaw/api/Table.java

@@ -236,7 +236,10 @@ public DataFrameWriter write() {
     return new DataFrameWriter(defaultWriterRegistry, this);
   }
 
-  /** Adds the given column to this table */
+  /**
+   * Adds the given column to this table. Column must either be empty or have size() == the
+   * rowCount() of the table they're being added to. Column names in the table must remain unique.
+   */
   @Override
   public Table addColumns(final Column<?>... cols) {
     for (final Column<?> c : cols) {
@@ -257,7 +260,9 @@ public void internalAddWithoutValidation(final Column<?> c) {
 
   /**
    * Throws an IllegalArgumentException if a column with the given name is already in the table, or
-   * if the number of rows in the column does not match the number of rows in the table
+   * if the number of rows in the column does not match the number of rows in the table. Regarding
+   * the latter rule, however, if the column is completely empty (size == 0), then it is filled with
+   * missing values to match the rowSize() as a convenience.
    */
   private void validateColumn(final Column<?> newColumn) {
     Preconditions.checkNotNull(
@@ -278,10 +283,18 @@ private void validateColumn(final Column<?> newColumn) {
 
   /**
    * Throws an IllegalArgumentException if the column size doesn't match the rowCount() for the
-   * table
+   * table. Columns that are completely empty, however, are initialized to match rowcount by filling
+   * with missing values
    */
   private void checkColumnSize(Column<?> newColumn) {
     if (columnCount() != 0) {
+      if (!isEmpty()) {
+        if (newColumn.isEmpty()) {
+          while (newColumn.size() < rowCount()) {
+            newColumn.appendMissing();
+          }
+        }
+      }
       Preconditions.checkArgument(
           newColumn.size() == rowCount(),
           "Column "
@@ -291,7 +304,9 @@ private void checkColumnSize(Column<?> newColumn) {
   }
 
   /**
-   * Adds the given column to this table at the given position in the column list
+   * Adds the given column to this table at the given position in the column list. Columns must
+   * either be empty or have size() == the rowCount() of the table they're being added to. Column
+   * names in the table must remain unique.
    *
    * @param index Zero-based index into the column list
    * @param column Column to be added

core/src/test/java/tech/tablesaw/api/TableTest.java

@@ -279,15 +279,24 @@ void appendPopulatedColumnToEmptyTable() {
         });
   }
 
+  @Test
+  void appendSmallerColumnToEmptyTable() {
+    assertThrows(
+        IllegalArgumentException.class,
+        () -> {
+          table.doubleColumn("f1").append(23).append(42);
+          table.addColumns(StringColumn.create("test", 1));
+        });
+  }
+
   @Test
   void testCountBy() {
     assertEquals(3, bush.countBy("who", "date").columnCount());
   }
 
   @Test
   void appendEmptyColumnToPopulatedTable() {
-    assertThrows(
-        IllegalArgumentException.class,
+    assertDoesNotThrow(
         () -> {
           table.doubleColumn("f1").append(23);
           table.addColumns(StringColumn.create("test"));