#37 javadoc: commons: Grid, JSON, math

assira.commons/src/main/java/net/ranides/assira/collection/Grid.java

@@ -12,6 +12,7 @@ import net.ranides.assira.collection.query.CQuery;
 import net.ranides.assira.collection.query.CQueryAbstract;
 import net.ranides.assira.collection.sets.SetUtils;
 import net.ranides.assira.generic.CompareUtils;
+import net.ranides.assira.math.MathUtils;
 import net.ranides.assira.reflection.BeanModel;
 
 import java.util.AbstractMap.SimpleImmutableEntry;
@@ -23,6 +24,17 @@ import java.util.stream.Stream;
 
 import static java.util.stream.Collectors.toList;
 
+/**
+ * Grid represents two dimensional table of values: list of cells of type T.
+ *
+ * The whole idea is to allow processing of data in columns, rows or as a list of records
+ * Grid can contain header which maps column names into column indexes.
+ *
+ * Using header you can view every column as a field with specified name,
+ * especially you can view list of rows as a list of records represented by maps.
+ *
+ * @param <T> type of values
+ */
 public class Grid<T> {
 
     private final List<String> head;
@@ -58,6 +70,15 @@ public class Grid<T> {
         return out;
     }
 
+    /**
+     * Creates new grid from records. Every records should have the same structure.
+     * Header is created from list of keys inside records.
+     * List of cells is created from maps (using already generated header)
+     *
+     * @param records records
+     * @param <T> type of cell
+     * @return grid
+     */
     public static <T> Grid<T> fromMap(List<? extends Map<String, T>> records) {
         List<String> head = records.stream()
             .flatMap(map -> map.keySet().stream())
@@ -65,16 +86,34 @@ public class Grid<T> {
             .collect(Collectors.toList());
 
         List<List<T>> data = records.stream()
-            .map((Map<String, T> r) -> head.stream().map(r::get).collect(toList()))
-            .collect(toList());
+            .map((Map<String, T> r) -> head.stream().map(r::get).collect(Collectors.toList()))
+            .collect(Collectors.toList());
 
         return new Grid<>(head, data);
     }
 
+    /**
+     * Creates new grid from records. Every records should have the same structure.
+     * Every object is converted into record using BeanModel.
+     * Header is created from list of keys inside records.
+     * List of cells is created from maps (using already generated header)
+     *
+     * @param rows rows
+     * @return grid
+     */
     public static Grid<Object> fromObjects(List<?> rows) {
         return fromMap(rows.stream().map(v -> BeanModel.typefor(v).fluent(v)).collect(toList()));
     }
 
+    /**
+     * Creates new grid from cells.
+     * It uses provided header to define mapping between column indexes and column names.
+     *
+     * @param header header
+     * @param rows rows
+     * @param <T> type of cell
+     * @return grid
+     */
     public static <T> Grid<T> fromRows(List<String> header, List<List<T>> rows) {
         return new Grid<>(header, rows);
     }
@@ -101,58 +140,146 @@ public class Grid<T> {
         return Objects.hash(head, data);
     }
 
+    /**
+     * Returns header defined for this grid.
+     * Header can be used as a query with column names, to process them sequentialy.
+     * Header implements fast lookup for names: "indexOf" returns result in O(1) time.
+     *
+     * @return header
+     */
     public GridHeader header() {
         return header;
     }
 
+    /**
+     * Returns cells organized in rows.
+     * Effectively, returned query is backed by list generated once.
+     *
+     * @return rows
+     */
     public GridRows rows() {
         return rows;
     }
 
+    /**
+     * Returns cells organized in columns.
+     * Effectively, returned query is backed by list generated once.
+     *
+     * @return columns
+     */
     public GridColumns columns() {
         return columns;
     }
 
+    /**
+     * Returns new grid with selected rows.
+     *
+     * @param selector list of row indexes to select
+     * @return grid
+     */
     public Grid<T> rows(IntList selector) {
         return new Grid<>(head, headmap, IntListUtils.map(selector, data::get));
     }
 
+    /**
+     * Returns new grid with selected columns
+     *
+     * @param selector list of column indexes to select
+     * @return grid
+     */
     public Grid<T> columns(IntList selector) {
         return new Grid<>(IntListUtils.map(selector, head::get), data.stream().map(row -> IntListUtils.map(selector, row::get)).collect(toList()));
     }
 
+    /**
+     * Returns cells as list of lists.
+     *
+     * @return cells
+     */
     public List<List<T>> list() {
         return data;
     }
 
+    /**
+     * Returns all cells as stream. Every cell is returned as GridCursor:
+     * cursor gives access to cell value and its position (row and column index).
+     *
+     * @return stream with cells
+     */
     public CQuery<GridCursor> stream() {
         return rows().flat(r -> r);
     }
 
+    /**
+     * Returns all rows as records (maps with keys defined by header).
+     *
+     * @return list of rows
+     */
     public List<Map<String, T>> records() {
         return ListUtils.map(data, GridRecord::new);
     }
 
+    /**
+     * Returns cell at specified position.
+     *
+     * @param row row
+     * @param column column
+     * @return cell value
+     */
     public T get(int row, int column) {
         return data.get(row).get(column);
     }
 
+    /**
+     * Returns cell at specified position.
+     *
+     * @param row row
+     * @param column column
+     * @return cell value
+     */
     public T get(int row, String column) {
         return data.get(row).get(headmap.getInt(column));
     }
 
+    /**
+     * Changes cell value at specified position
+     * @param row row
+     * @param column column
+     * @param value value
+     */
     public void set(int row, int column, T value) {
         data.get(row).set(column, value);
     }
 
+    /**
+     * Changes cell value at specified position
+     * @param row row
+     * @param column column
+     * @param value value
+     */
     public void set(int row, String column, T value) {
         data.get(row).set(headmap.getInt(column), value);
     }
 
+    /**
+     * Returns new grid with sorted rows by specified columns.
+     * Order of columns inside selector is important and defines comparision priority.
+     *
+     * @param selector list of columns to use in sort
+     * @return grid
+     */
     public Grid<T> sort(IntList selector) {
         return new Grid<>(head, headmap, data.stream().sorted((a, b) -> rowcmp(selector, a, b)).collect(toList()));
     }
 
+    /**
+     * Transform every cell into new value.
+     * Mapping function gets GridCursor, which means you can use not only cell value, but cell position too.
+     *
+     * @param mapper mapper
+     * @param <R> new cell type
+     * @return grid
+     */
     public <R> Grid<R> map(Function<GridCursor, R> mapper) {
         List<List<R>> out = new ArrayList<>(data.size());
         for(int r=0, R=rows.size(); r<R; r++) {
@@ -176,6 +303,10 @@ public class Grid<T> {
         return 0;
     }
 
+    private boolean isValid(int row, int column) {
+        return row < data.size() && column < data.get(row).size();
+    }
+
     @RequiredArgsConstructor
     private class GridRecord extends AMap<String, T> {
 
@@ -207,6 +338,10 @@ public class Grid<T> {
         }
     }
 
+    /**
+     * GridHeader is essentially CQuery<String> backed by list, but with opitimized lookup by name.
+     * Method "indexOf(name)" will return in constant time.
+     */
     public class GridHeader extends CQueryAbstract<String> {
 
         private GridHeader() {
@@ -243,8 +378,20 @@ public class Grid<T> {
             return head.iterator();
         }
 
+        @Override
+        public int indexOf(String value) {
+            return headmap.get(value);
+        }
+
+        @Override
+        public int lastIndexOf(String value) {
+            return headmap.get(value);
+        }
     }
 
+    /**
+     * GridColumns is essentially CQuery backed by list of columns.
+     */
     public class GridColumns extends CQueryAbstract<GridColumn> {
 
         private final List<GridColumn> list;
@@ -273,6 +420,11 @@ public class Grid<T> {
             return head.size();
         }
 
+        @Override
+        public boolean hasFastList() {
+            return true;
+        }
+
         @Override
         public Stream<GridColumn> stream() {
             return list.stream();
@@ -283,12 +435,20 @@ public class Grid<T> {
             return list.iterator();
         }
 
-        public GridColumn get(int index) {
-            return list.get(index);
+        @Override
+        public List<GridColumn> list() {
+            return list;
         }
 
     }
 
+    /**
+     * GridColumn is essentially CQuery not backed by any in-memory structure.
+     * GridColumn is a view and reads cells in realtime, by just using column index as bound argument.
+     *
+     * It allows iteration through all rows and extract cell in specified column.
+     * It allows fast read/write to cell using row index.
+     */
     @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
     public class GridColumn extends CQueryAbstract<GridCursor> {
 
@@ -324,15 +484,38 @@ public class Grid<T> {
             return stream().iterator();
         }
 
+        @Override
+        public Optional<GridCursor> at(int row) {
+            return isValid(row, index) ? Optional.of(new GridCursor(row, index)) : Optional.empty();
+        }
+
+        /**
+         * Fast access to cell data inside column.
+         * @param row row
+         * @return cell value
+         */
         public T get(int row) {
             return data.get(row).get(index);
         }
 
+        /**
+         * Fast access to cell data inside column.
+         * @param row row
+         * @param value new value
+         * @return old value
+         */
+        public T set(int row, T value) {
+            return data.get(row).set(index, value);
+        }
     }
 
+    /**
+     * GridRows is essentially CQuery backed by list of rows.
+     */
     public class GridRows extends CQueryAbstract<GridRow> {
 
-        private final List<GridRow> list = IntStream.range(0, size()).mapToObj(i -> new GridRow(i)).collect(toList());
+        private final List<GridRow> list = IntStream.range(0, size())
+            .mapToObj(i -> new GridRow(i)).collect(Collectors.toList());
 
         private GridRows() {
             // do nothing
@@ -353,6 +536,11 @@ public class Grid<T> {
             return false;
         }
 
+        @Override
+        public boolean hasFastList() {
+            return true;
+        }
+
         @Override
         public int size() {
             return data.size();
@@ -368,12 +556,20 @@ public class Grid<T> {
             return list.iterator();
         }
 
-        public GridRow get(int index) {
-            return list.get(index);
+        @Override
+        public List<GridRow> list() {
+            return list;
         }
 
     }
 
+    /**
+     * GridRow is essentially CQuery not backed by any in-memory structure.
+     * GridRow is a view and reads cells in realtime, by just using rows index as bound argument.
+     *
+     * It allows iteration through all columns and extract cells in specified row.
+     * It allows fast read/write to cell using column index.
+     */
     @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
     public class GridRow extends CQueryAbstract<GridCursor> {
 
@@ -409,16 +605,58 @@ public class Grid<T> {
             return stream().iterator();
         }
 
+        @Override
+        public Optional<GridCursor> at(int column) {
+            return isValid(index, column) ? Optional.of(new GridCursor(index, column)) : Optional.empty();
+        }
+
+        /**
+         * Fast access to cell data inside row.
+         *
+         * @param column column
+         * @return value
+         */
         public T get(int column) {
             return data.get(index).get(column);
         }
 
+        /**
+         * Fast access to cell data inside row.
+         *
+         * @param column column
+         * @return value
+         */
         public T get(String column) {
             return data.get(index).get(headmap.getInt(column));
         }
+
+        /**
+         * Fast access to cell data inside row.
+         *
+         * @param column column
+         * @param value new value
+         * @return old value
+         */
+        public T set(int column, T value) {
+            return data.get(index).set(column, value);
+        }
+
+        /**
+         * Fast access to cell data inside row.
+         *
+         * @param column column
+         * @param value new value
+         * @return old value
+         */
+        public T set(String column, T value) {
+            return data.get(index).set(headmap.getInt(column), value);
+        }
     }
 
 
+    /**
+     * It is simple view exposing cell's value and its position
+     */
     @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
     public class GridCursor {
 
@@ -426,20 +664,41 @@ public class Grid<T> {
 
         private final int column;
 
+        /**
+         * Returns cell's position
+         *
+         * @return row index
+         */
         public int row() {
             return row;
         }
 
+        /**
+         * Returns cell's position
+         *
+         * @return column index
+         */
         public int column() {
             return column;
         }
 
+        /**
+         * Fast access to cell data at cursor position.
+         *
+         * @return value
+         */
         public T get() {
             return data.get(row).get(column);
         }
 
-        public void set(T value) {
-            data.get(row).set(column, value);
+        /**
+         * Fast access to cell data at cursor position.
+         *
+         * @param value new value
+         * @return old value
+         */
+        public T set(T value) {
+            return data.get(row).set(column, value);
         }
 
     }

assira.commons/src/main/java/net/ranides/assira/json/JSON.java

@@ -16,8 +16,8 @@ import net.ranides.assira.reflection.*;
 import java.io.IOException;
 
 /**
- * Klasa używana tylko do prezentowania obiektów jako tekst bardziej
- * reprezentatywnie niż za pomocą wbudowanych metod "toString".
+ * This class is used only to format objects into text in a bit more meaningful than default toString method.
+ * Additionally, it can be used to convert any bean compatible object to/from JSON (including lexical cast).
  *
  * @author ranides
  */
@@ -31,15 +31,40 @@ public final class JSON {
         MAPPER.configure(SerializationFeature.INDENT_OUTPUT, true);
     }
 
+    /**
+     * Lexical cast: it serializes object into text and then tries to create object of specified type.
+     *
+     * @param value input value
+     * @param clazz target type
+     * @param <T> target type
+     * @return new object created from JSON
+     * @throws JSONCastException when incompatible cast
+     */
     public static <T> T cast(Object value, Class<T> clazz) throws JSONCastException {
         return cast(value, IClass.typeinfo(clazz));
     }
 
+    /**
+     * Lexical cast: it serializes object into text and then tries to create object of specified type.
+     *
+     * @param value input value
+     * @param type target type
+     * @param <T> target type
+     * @return new object created from JSON
+     * @throws JSONCastException when incompatible cast
+     */
     @SuppressWarnings("unchecked")
     public static <T> T cast(Object value, IClass<T> type) throws JSONCastException {
         return (T) JSON.fromJSON(JSON.toJSON(value), (IClass<?>) type);
     }
 
+    /**
+     * Converts value into JSON using default ObjectMapper (it tries to follow JavaBean convention).
+     *
+     * @param value input
+     * @return serialized object
+     * @throws ClassCastException when incompatible cast
+     */
     public static String toJSON(Object value) throws ClassCastException {
         try {
             return MAPPER.writeValueAsString(value);
@@ -48,10 +73,28 @@ public final class JSON {
         }
     }
 
+    /**
+     * Converts JSON into object of specified type using default ObjectMapper  (it tries to follow JavaBean convention).
+     *
+     * @param value input text
+     * @param type target type
+     * @param <T> target type
+     * @return new object
+     * @throws JSONCastException when incompatible cast
+     */
     public static <T> T fromJSON(String value, Class<T> type) throws JSONCastException {
         return fromJSON(value, IClass.typeinfo(type));
     }
-    
+
+    /**
+     * Converts JSON into object of specified type using default ObjectMapper  (it tries to follow JavaBean convention).
+     *
+     * @param value input text
+     * @param type target type
+     * @param <T> target type
+     * @return new object
+     * @throws JSONCastException when incompatible cast
+     */
     @SuppressWarnings("unchecked")
     public static <T> T fromJSON(String value, IClass<T> type) throws JSONCastException {
         try {

assira.commons/src/main/java/net/ranides/assira/math/LFSR.java

@@ -9,7 +9,9 @@ package net.ranides.assira.math;
 import java.util.Random;
 
 /**
- * PRNG generates with very long series without cycle.
+ * PRNG generator with very long series without cycle.
+ * <a href="https://en.wikipedia.org/wiki/Linear-feedback_shift_register">See LSFR at Wikipedia</a>
+ *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
 public final class LFSR extends Random {
@@ -22,10 +24,18 @@ public final class LFSR extends Random {
     
     private boolean[] vector;
 
+    /**
+     * Creates new LFSR seeding with current time.
+     */
     public LFSR() {
         this( (int)System.nanoTime() );
     }
-    
+
+    /**
+     * Creates new LFSR seeding with specified value
+     *
+     * @param seed seed
+     */
     public LFSR(int seed) {
         super(seed);
     }

assira.commons/src/main/java/net/ranides/assira/math/MathStats.java

@@ -10,21 +10,52 @@ import net.ranides.assira.generic.CompareUtils;
 import java.util.DoubleSummaryStatistics;
 import java.util.List;
 
+/**
+ * Rudimentary implementation of statistic measures: mode, standard deviation
+ */
 public class MathStats {
 
+    /**
+     * Traverses whole input and establishes mode of data.
+     *
+     * @param data input
+     * @param <T> input
+     * @return mode stats
+     */
     public static <T> Mode<T> mode(CQuery<T> data) {
         return new Mode<>(data);
     }
 
+    /**
+     * Traverses whole input and calculates average, variance and deviation
+     * @param data input
+     * @return standard deviation stats
+     */
     public static StandardDeviation deviation(CQuery<? extends Number> data) {
         return new StandardDeviation(data);
     }
 
+    /**
+     * Basic statistics about most popular element
+     *
+     * @param <T> type of element
+     */
     @Data
     public static class Mode<T> {
 
+        /**
+         * value of most popular element
+         */
         private final T value;
+
+        /**
+         * number of occurrences of element inside data
+         */
         private final int count;
+
+        /**
+         * number of elements in data
+         */
         private final int domain;
 
         private Mode(CQuery<T> data) {
@@ -76,11 +107,25 @@ public class MathStats {
         }
     }
 
+    /**
+     * Basic statistics about classical average
+     */
     @Data
     public static class StandardDeviation {
 
+        /**
+         * classic arithmetical average
+         */
         private final double average;
+
+        /**
+         * classic variance
+         */
         private final double variance;
+
+        /**
+         * classic standard deviation
+         */
         private final double deviation;
 
         private StandardDeviation(CQuery<? extends Number> data) {

assira.commons/src/main/java/net/ranides/assira/math/RandomUtils.java

@@ -6,21 +6,38 @@ import net.ranides.assira.collection.lists.IntList;
 import java.util.List;
 import java.util.Random;
 
+/**
+ * Helper methods for randomizing data.
+ */
 public class RandomUtils {
 
     /**
      * Reimplementation of
      * <a href="https://tfetimes.com/wp-content/uploads/2015/04/ProgrammingPearls2nd.pdf">Knuth's algorithm</a>.
      * It generates count distinct numbers from range [begin,end). <br>Complexity: {@code O(count)}.
-     * @param count
-     * @param begin
-     * @param end
-     * @return
+     *
+     * It uses default {@code Random} to get random bits.
+     *
+     * @param count count
+     * @param begin begin
+     * @param end end
+     * @return numbers
      */
     public static IntList uniqueInts(int count, int begin, int end) {
         return uniqueInts(new Random(), count, begin, end);
     }
 
+    /**
+     * Reimplementation of
+     * <a href="https://tfetimes.com/wp-content/uploads/2015/04/ProgrammingPearls2nd.pdf">Knuth's algorithm</a>.
+     * It generates count distinct numbers from range [begin,end). <br>Complexity: {@code O(count)}.
+     *
+     * @param rng source of random bits
+     * @param count count
+     * @param begin begin
+     * @param end end
+     * @return numbers
+     */
     public static IntList uniqueInts(Random rng, int count, int begin, int end) {
         int n = end - begin;
         IntList result = new IntArrayList(count);
@@ -33,10 +50,26 @@ public class RandomUtils {
         return result;
     }
 
+    /**
+     * Choices random element from array.
+     *
+     * @param rng source of random bits
+     * @param values values
+     * @param <T> value type
+     * @return value
+     */
     public static <T> T element(Random rng, T[] values) {
         return values[rng.nextInt(values.length)];
     }
 
+    /**
+     * Choices random element from list.
+     *
+     * @param rng source of random bits
+     * @param values values
+     * @param <T> value type
+     * @return value
+     */
     public static <T> T element(Random rng, List<T> values) {
         return values.get(rng.nextInt(values.size()));
     }

assira.commons/src/main/java/net/ranides/assira/math/Randomizer.java

@@ -6,12 +6,21 @@ import net.ranides.assira.collection.lists.IntList;
 import java.awt.*;
 import java.util.Random;
 
+/**
+ * Simple helper generating random values for wide range of standard types.
+ * It is just facade: it can be seeded by any implementation of {@link Random}
+ */
 public class Randomizer {
 
     private static final String CHARACTERS = "qwertyuiopasdfghjklzxcvbnmQWERTYUIOPASDFGHJKLZXCVBNM1234567890      ";
 
     private final Random rng;
 
+    /**
+     * Creates new randomizer which retrieves random bits from specified PRNG
+     *
+     * @param rng rng
+     */
     public Randomizer(Random rng) {
         this.rng = rng;
     }
@@ -37,14 +46,31 @@ public class Randomizer {
         return result;
     }
 
+    /**
+     * Returns number from range [0,1). That means: zero inclusive, 1 exclusive.
+     * @return float
+     */
     public float nextFloat() {
         return rng.nextFloat();
     }
 
+    /**
+     * Returns number from range [0,upper). That means: zero inclusive, "upper" exclusive.
+     *
+     * @param upper upper
+     * @return number
+     */
     public float nextFloat(float upper) {
         return upper * rng.nextFloat();
     }
 
+    /**
+     * Returns number from range [lower,upper). That means: "lower" inclusive, "upper" exclusive.
+     *
+     * @param lower lower
+     * @param upper upper
+     * @return number
+     */
     public float nextFloat(float lower, float upper) {
         if (lower >= upper || Double.isInfinite(lower) || Double.isInfinite(upper) || Double.isNaN(lower) || Double.isNaN(upper)) {
             throw new IllegalRange(lower, upper);
@@ -53,14 +79,32 @@ public class Randomizer {
         return u * upper + (1.0f - u) * lower;
     }
 
+    /**
+     * Returns number from range [0,1). That means: zero inclusive, 1 exclusive.
+     *
+     * @return number
+     */
     public double nextDouble() {
         return rng.nextDouble();
     }
 
+    /**
+     * Returns number from range [0,upper). That means: zero inclusive, "upper" exclusive.
+     *
+     * @param upper upper
+     * @return number
+     */
     public double nextDouble(double upper) {
         return upper * rng.nextDouble();
     }
 
+    /**
+     * Returns number from range [lower,upper). That means: "lower" inclusive, "upper" exclusive.
+     *
+     * @param lower lower
+     * @param upper upper
+     * @return number
+     */
     public double nextDouble(double lower, double upper) {
         if (lower >= upper || Double.isInfinite(lower) || Double.isInfinite(upper) || Double.isNaN(lower) || Double.isNaN(upper)) {
             throw new IllegalRange(lower, upper);
@@ -69,38 +113,95 @@ public class Randomizer {
         return u * upper + (1.0 - u) * lower;
     }
 
+    /**
+     * Returns byte value
+     * @return byte
+     */
     public byte nextByte() {
         return (byte)nextInt(Byte.MIN_VALUE, Byte.MAX_VALUE);
     }
 
+    /**
+     * Returns byte value from range [0,upper). That means: zero inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can't be returned
+     *
+     * @param upper upper
+     * @return byte
+     */
     public byte nextByte(byte upper) {
         return (byte)nextInt(upper);
     }
 
+    /**
+     * Returns byte from range [lower,upper). That means: "lower" inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can be returned, if "lower" is negative
+     *
+     * @param lower lower
+     * @param upper upper
+     * @return byte
+     */
     public byte nextByte(byte lower, byte upper) {
         return (byte)nextInt(lower, upper);
     }
 
+    /**
+     * Returns short value
+     * @return short
+     */
     public short nextShort() {
         return (short)nextInt(Short.MIN_VALUE, Short.MAX_VALUE);
     }
 
+    /**
+     * Returns short value from range [0,upper). That means: zero inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can't be returned
+     *
+     * @param upper upper
+     * @return short
+     */
     public short nextShort(short upper) {
         return (short)nextInt(upper);
     }
 
+    /**
+     * Returns short from range [lower,upper). That means: "lower" inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can be returned, if "lower" is negative
+     *
+     * @param lower lower
+     * @param upper upper
+     * @return short
+     */
     public short nextShort(short lower, short upper) {
         return (short)nextInt(lower, upper);
     }
 
+    /**
+     * Returns int value
+     * @return int
+     */
     public int nextInt() {
         return rng.nextInt();
     }
 
+    /**
+     * Returns int value from range [0,upper). That means: zero inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can't be returned
+     *
+     * @param upper upper
+     * @return int
+     */
     public int nextInt(int upper) {
         return rng.nextInt(upper);
     }
 
+    /**
+     * Returns int from range [lower,upper). That means: "lower" inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can be returned, if "lower" is negative
+     *
+     * @param lower lower
+     * @param upper upper
+     * @return int
+     */
     public int nextInt(int lower, int upper) {
         if(lower >= upper) {
             throw new IllegalRange(lower, upper);
@@ -108,10 +209,21 @@ public class Randomizer {
         return lower + rng.nextInt(upper - lower);
     }
 
+    /**
+     * Returns long value
+     * @return long
+     */
     public long nextLong() {
         return rng.nextLong();
     }
 
+    /**
+     * Returns long value from range [0,upper). That means: zero inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can't be returned
+     *
+     * @param upper upper
+     * @return long
+     */
     public long nextLong(long upper) {
         if(upper <=0) {
             throw new IllegalRange(0, upper);
@@ -128,6 +240,14 @@ public class Randomizer {
         return r;
     }
 
+    /**
+     * Returns long from range [lower,upper). That means: "lower" inclusive, "upper" exclusive.
+     * Please note, that it means that negative values can be returned, if "lower" is negative
+     *
+     * @param lower lower
+     * @param upper upper
+     * @return long
+     */
     public long nextLong(long lower, long upper) {
         if(lower >= upper) {
             throw new IllegalRange(lower, upper);
@@ -149,32 +269,42 @@ public class Randomizer {
         }
     }
 
+    /**
+     * Returns String of specified "size" containing chars from allowed list.
+     * @param size size
+     * @param chars chars
+     * @return String
+     */
     public String text(int size, String chars) {
         char[] buffer = new char[size];
         for(int i=0; i<size; i++) { buffer[i] = character(chars); }
         return new String(buffer);
     }
 
+    /**
+     * Returns String of specified "size" containing alphanumeric chars and spaces.
+     * @param size size
+     * @return String
+     */
     public String text(int size) {
         return text(size, CHARACTERS);
     }
 
     /**
-     * Losuje kolor o maksymalnym nasyceniu (Saturation), dowolnej barwie (Hue) i
-     * jasności z podanego zakresu.
-     * @param min
-     * @param max
-     * @return
+     * Returns fully saturated color, with random hue and brightness from specified range.
+     * @param min min brightness
+     * @param max max brightness
+     * @return color
      */
     public Color color(float min, float max) {
         return Color.getHSBColor(nextFloat(), 1, nextFloat(min,max));
     }
 
     /**
-     * Losuje kolor pośredni między dwoma podanymi.
-     * @param min
-     * @param max
-     * @return
+     * Returns some intermediate color between two specified edge colors.
+     * @param min edge color
+     * @param max edge color
+     * @return color
      */
     public Color color(Color min, Color max) {
         return new Color(
@@ -185,17 +315,17 @@ public class Randomizer {
     }
 
     /**
-     * Zwraca dowolny losowy znak alfanumeryczny
-     * @return
+     * Returns random alphanumeric character (including space)
+     * @return char
      */
     public char character() {
         return character(CHARACTERS);
     }
 
     /**
-     * Zwraca losowy znak z podanego zbioru.
-     * @param chars
-     * @return
+     * Returns random character from specified set.
+     * @param chars chars
+     * @return char
      */
     public char character(String chars) {
         return chars.charAt( nextInt(chars.length()) );