Package JavaDoc to clarify what this artifact is & does

Full disclosure: I LIKE the concept of what one could call
MockitoNotImplementedExceptionAnswer, and have separately implemented
the same (one can find this idea publicly on the web in several places).

I don't think having this configured by default automagically is good;
that is just too sneaky and surprising IMHO.  One should be able to use
a popular utility and expect it to behave as it's documented?

No offense meant to anyone.  None taken I hope.

Change-Id: Idf30e82c2cb1777065de781a5eecc220416161ca
Signed-off-by: Michael Vorburger <vorburger@redhat.com>

diff --git a/common/mockito-configuration/src/main/java/org/mockito/configuration/package-info.java b/common/mockito-configuration/src/main/java/org/mockito/configuration/package-info.java
new file mode 100644 (file)
index 0000000..5031862
--- /dev/null
+++ b/common/mockito-configuration/src/main/java/org/mockito/configuration/package-info.java
@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2016 Red Hat and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+/**
+ * Black magic Mockito utility.
+ *
+ * <p>This artifact is "black magic" because by merely depending on it (by its
+ * presence on the classpath, without ever using any of its classes), all usages
+ * of core Mockito.mock() in your existing tests will suddenly behave
+ * differently automagically all by themselves: They will throw
+ * ThrowsUnstubbedMethodException instead of returning null etc. as in default
+ * Mockito. (This "magic" is also the technical reason why this is package
+ * org.mockito.configuration instead of org.opendaylight.*)
+ *
+ * <p>TODO Point to the "other/new artifact with more sane Mockito helper, with
+ * explicit API.
+ *
+ * @see MockitoConfiguration
+ * @see org.mockito.configuration.IMockitoConfiguration
+ */
+package org.mockito.configuration;