Improved package API documentation.

main/src/mockit/integration/junit4/package-info.java

@@ -5,22 +5,32 @@
 
 /**
  * Provides integration with <em>JUnit 4.x</em> test runners, for version 4.5 or newer.
- * Contains the {@link mockit.integration.junit4.JMockit} custom class runner.
+ * Contains the {@link mockit.integration.junit4.JMockit} custom test runner (which is not an actual test runner, but
+ * just a way to ensure that JMockit gets properly initialized - a better way is to simply put {@code jmockit.jar}
+ * <em>before</em> {@code junit.jar} in the test runtime classpath).
  * <p/>
  * This integration provides the following benefits to test code:
  * <ol>
- * <li>
- * Expected invocations specified through the Expectations API are automatically verified before the execution of a test
- * is completed.
- * </li>
- * <li>
- * Mock-up classes applied with the Mockups API from inside a method annotated as a {@code @Test} or a {@code @Before}
- * method are discarded right after the execution of the test method or the whole test, respectively.
- * </li>
- * <li>
- * Test methods accept <em>mock parameters</em>, whose values are mocked instances automatically created by JMockit and
- * passed by the test runner when the test method is executed.
- * </li>
+ *    <li>
+ *       Instance fields annotated with {@code @Tested}, {@code @Injectable}, {@code @Mocked}, or {@code @Capturing}
+ *       are properly initialized.
+ *    </li>
+ *    <li>
+ *       Test methods accept <em>mock parameters</em> (annotated with {@code @Injectable}, {@code @Mocked}, or
+ *       {@code @Capturing}), whose values are mocked instances automatically created by JMockit and passed by the test
+ *       runner when the test method is executed.
+ *    </li>
+ *    <li>
+ *       Expected invocations specified through the Expectations API are automatically verified before the execution of
+ *       a test is completed.
+ *    </li>
+ *    <li>
+ *       Mock-up classes applied with the Mockups API from inside a method annotated as a {@code @Test} or a
+ *       {@code @Before} method are discarded right after the execution of the test method or the whole test,
+ *       respectively.
+ *       Similarly, mock-ups applied from a {@code @BeforeClass} method are discarded after all tests in a test class
+ *       have executed.
+ *    </li>
  * </ol>
  */
 package mockit.integration.junit4;

main/src/mockit/package-info.java

@@ -4,17 +4,33 @@
  */
 
 /**
- * Provides the classes and annotations used when writing tests with the JMockit mocking and faking APIs.
+ * Provides the classes and annotations used when writing tests with the JMockit APIs.
+ * <p/>
+ * The {@linkplain mockit.Tested @Tested} annotation allows for the instantiation of classes under test, with the
+ * injection and/or recursive instantiation of dependencies.
+ * It can inject mocked instances when used in combination with the {@linkplain mockit.Injectable @Injectable} mocking
+ * annotation, and also inject <em>non-mocked</em> (real) instances when applied as
+ * {@code @Tested(fullyInitialized = true)}.
+ * Non-mocked instances are either automatically created or obtained from other {@code @Tested} fields.
  * <p/>
  * The {@link mockit.Expectations} class provides an API for the <em>record-replay</em> model of recording expected
  * invocations which are later replayed and implicitly verified.
- * This API makes use of the {@linkplain mockit.Mocked @Mocked} annotation (among others).
+ * This API makes use of the {@linkplain mockit.Mocked @Mocked}, {@linkplain mockit.Injectable @Injectable}, and
+ * {@linkplain mockit.Capturing @Capturing} <em>mocking</em> annotations.
  * The {@link mockit.Verifications} class extends the record-replay model to a <em>record-replay-verify</em> model,
  * where expectations that were not recorded can be verified explicitly <em>after</em> exercising the code under test
  * (ie, after the replay phase).
+ * The {@link mockit.Invocation} class and the {@link mockit.Delegate} interface are also part of this API; they can be
+ * used for recording expectations with custom results, and for the implementation of custom argument matchers.
+ * <p/>
+ * {@linkplain mockit.MockUp <code>MockUp&lt;T></code>} is a generic base class (where {@code T} is the type to be
+ * faked) which allows the definition of fake implementations for external classes or interfaces.
+ * Methods in a mock-up subclass that take the place of the "real" methods in class {@code T} are indicated with the
+ * {@linkplain mockit.Mock @Mock} annotation.
+ * Such methods can also (optionally) have an {@link mockit.Invocation} parameter.
  * <p/>
- * The {@linkplain mockit.MockUp <code>MockUp&lt;T></code>} generic class (where {@code T} is the mocked type) allows
- * the definition of fake implementations for external classes or interfaces.
+ * Finally, the {@link mockit.Deencapsulation} class provides several Reflection-based utility methods, for the
+ * occasional cases where a {@code private} field needs to be accessed, etc.
  * <p/>
  * For a description with examples of the <em>Expectations</em> API, see the
  * "<a href="http://jmockit.org/tutorial/Mocking.html">Mocking</a>" chapter in the Tutorial.