#310 - Improve javadoc for OrderLine and ChargeLine.

src/main/java/org/salespointframework/order/ChargeLine.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019 the original author or authors.
+ * Copyright 2017-2020 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.
@@ -35,8 +35,14 @@
 import org.springframework.util.Assert;
 
 /**
- * A chargeline represents extra expenses like shipping. This class is immutable.
+ * A charge line represents extra expenses, such as shipping, for an
+ * {@link Order} as a whole. Expenses for an individual {@link OrderLine} can be
+ * modeled using the {@link AttachedChargeLine} sub-class.
+ * <p>
+ * This class is immutable.
  * 
+ * @see AttachedChargeLine
+ * @see OrderLine
  * @author Thomas Dedek
  * @author Paul Henke
  * @author Oliver Gierke

src/main/java/org/salespointframework/order/OrderLine.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019 the original author or authors.
+ * Copyright 2017-2020 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.
@@ -35,8 +35,16 @@
 import org.springframework.util.Assert;
 
 /**
- * An order line
+ * An order line represents the price and the {@link Quantity} of a
+ * {@link Product} that is intended to be purchased as part of an {@link Order}.
+ * <p>
+ * Order lines should not be used to represent expenses for services, such as
+ * shipping. For this purpose, {@link ChargeLine} should be used instead.
+ * <p>
+ * Note that the constructor of this class creates a copy of the product's name
+ * and price, so that changes to those attributes do not affect existing orders.
  * 
+ * @see ChargeLine
  * @author Paul Henke
  * @author Oliver Gierke
  */