diff --git a/src/main/java/org/apache/commons/math3/optim/linear/package-info.java b/src/main/java/org/apache/commons/math3/optim/linear/package-info.java
index 64c46973f..b9005899e 100644
--- a/src/main/java/org/apache/commons/math3/optim/linear/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/linear/package-info.java
@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim.linear;
 
 /**
  * Optimization algorithms for linear constrained problems.
  */
+package org.apache.commons.math3.optim.linear;
diff --git a/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/gradient/package-info.java b/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/gradient/package-info.java
index e516c7d8e..9dd9c5aaa 100644
--- a/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/gradient/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/gradient/package-info.java
@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim.nonlinear.scalar.gradient;
 
 /**
  * This package provides optimization algorithms that require derivatives.
  */
+package org.apache.commons.math3.optim.nonlinear.scalar.gradient;
diff --git a/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/noderiv/package-info.java b/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/noderiv/package-info.java
index 25af94bc3..4afeb5082 100644
--- a/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/noderiv/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/noderiv/package-info.java
@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim.nonlinear.scalar.noderiv;
 
 /**
  * This package provides optimization algorithms that do not require derivatives.
  */
+package org.apache.commons.math3.optim.nonlinear.scalar.noderiv;
diff --git a/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/package-info.java b/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/package-info.java
index a3ee653ae..d65533a13 100644
--- a/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/nonlinear/scalar/package-info.java
@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim.nonlinear.scalar;
 
 /**
  * Algorithms for optimizing a scalar function.
  */
+package org.apache.commons.math3.optim.nonlinear.scalar;
diff --git a/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/jacobian/package-info.java b/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/jacobian/package-info.java
index 169914711..d68345254 100644
--- a/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/jacobian/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/jacobian/package-info.java
@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim.nonlinear.vector.jacobian;
 
 /**
  * This package provides optimization algorithms that require derivatives.
  */
+package org.apache.commons.math3.optim.nonlinear.vector.jacobian;
diff --git a/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/package-info.java b/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/package-info.java
index 75e3585c3..7f894ca37 100644
--- a/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/nonlinear/vector/package-info.java
@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim.nonlinear.vector;
 
 /**
  * Algorithms for optimizing a vector function.
  */
+package org.apache.commons.math3.optim.nonlinear.vector;
diff --git a/src/main/java/org/apache/commons/math3/optim/package-info.java b/src/main/java/org/apache/commons/math3/optim/package-info.java
index 080eb1b8c..fcfa4fd81 100644
--- a/src/main/java/org/apache/commons/math3/optim/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/package-info.java
@@ -14,13 +14,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim;
 
 /**
  * <p>
  *  Generally, optimizers are algorithms that will either
- *  {@link GoalType#MINIMIZE minimize} or {@link GoalType#MAXIMIZE maximize}
- *  a scalar function, called the {@link ObjectiveFunction <em>objective
+ *  {@link org.apache.commons.math3.optim.GoalType#MINIMIZE minimize} or
+ *  {@link org.apache.commons.math3.optim.GoalType#MAXIMIZE maximize}
+ *  a scalar function, called the
+ *  {@link org.apache.commons.math3.optim.ObjectiveFunction <em>objective
  *  function</em>}.
  *  <br/>
  *  For some scalar objective functions the gradient can be computed (analytically
@@ -57,10 +58,12 @@ package org.apache.commons.math3.optim;
  *
  * <p>
  *  This package provides common functionality for the optimization algorithms.
- *  Abstract classes ({@link BaseOptimizer} and {@link BaseMultivariateOptimizer})
- *  define boiler-plate code for storing {@link MaxEval evaluations} and
- *  {@link MaxIter iterations} counters and a user-defined
- *  {@link ConvergenceChecker convergence checker}.
+ *  Abstract classes ({@link org.apache.commons.math3.optim.BaseOptimizer} and
+ *  {@link org.apache.commons.math3.optim.BaseMultivariateOptimizer}) contain
+ *  boiler-plate code for storing {@link org.apache.commons.math3.optim.MaxEval
+ *  evaluations} and {@link org.apache.commons.math3.optim.MaxIter iterations}
+ *  counters and a user-defined
+ *  {@link org.apache.commons.math3.optim.ConvergenceChecker convergence checker}.
  * </p>
  *
  * <p>
@@ -71,3 +74,4 @@ package org.apache.commons.math3.optim;
  *  This could be useful to avoid being trapped in a local extremum.
  * </p>
  */
+package org.apache.commons.math3.optim;
diff --git a/src/main/java/org/apache/commons/math3/optim/univariate/package-info.java b/src/main/java/org/apache/commons/math3/optim/univariate/package-info.java
index e1532c6a3..2273babb2 100644
--- a/src/main/java/org/apache/commons/math3/optim/univariate/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optim/univariate/package-info.java
@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.math3.optim.univariate;
 
 /**
  * One-dimensional optimization algorithms.
  */
+package org.apache.commons.math3.optim.univariate;
diff --git a/src/main/java/org/apache/commons/math3/optimization/package-info.java b/src/main/java/org/apache/commons/math3/optimization/package-info.java
index 1e8899259..0fee52d9b 100644
--- a/src/main/java/org/apache/commons/math3/optimization/package-info.java
+++ b/src/main/java/org/apache/commons/math3/optimization/package-info.java
@@ -15,6 +15,12 @@
  * limitations under the License.
  */
 /**
+ * <h2>All classes and sub-packages of this package are deprecated.</h2>
+ * <h3>Please use their replacements, to be found under
+ *  <ul>
+ *   <li>{@link org.apache.commons.math3.optim}</li>
+ *   <li>{@link org.apache.commons.math3.fitting}</li>
+ * </h3>
  *
  * <p>
  * This package provides common interfaces for the optimization algorithms