DataHandleService: document behavior when encountering null

Author: gab1one

src/main/java/org/scijava/io/handle/DataHandleService.java

@@ -71,8 +71,9 @@ default Class<Location> getType() {
 	 *
 	 * @param location the location to test
 	 * @return The result of {@link DataHandle#exists()} on a newly created handle
-	 *         on this location
-	 * @throws IOException
+	 *         on this location. Also returns {@code false} if the handle can not
+	 *         be created.
+	 * @throws IOException if the creation of the handle fails exceptionally
 	 */
 	default boolean exists(final Location location) throws IOException {
 		try (DataHandle<Location> handle = create(location)) {
@@ -85,6 +86,8 @@ default boolean exists(final Location location) throws IOException {
 	 * reading.
 	 *
 	 * @param handle the handle to wrap
+	 * @return The handle wrapped in a read-only buffer, or {@code null} if the
+	 *         input handle is {@code null}
 	 * @see ReadBufferDataHandle#ReadBufferDataHandle(DataHandle)
 	 */
 	default DataHandle<Location> readBuffer(final DataHandle<Location> handle) {
@@ -95,7 +98,10 @@ default DataHandle<Location> readBuffer(final DataHandle<Location> handle) {
 	 * Creates a {@link DataHandle} on the provided {@link Location} wrapped in a
 	 * read-only buffer for accelerated reading.
 	 *
-	 * @param location the handle to wrap
+	 * @param location the Location to create a buffered handle on.
+	 * @return A {@link DataHandle} on the provided location wrapped in a
+	 *         read-only buffer, or {@code null} if no handle could be created for
+	 *         the location.
 	 * @see ReadBufferDataHandle#ReadBufferDataHandle(DataHandle)
 	 */
 	default DataHandle<Location> readBuffer(final Location location) {
@@ -108,6 +114,8 @@ default DataHandle<Location> readBuffer(final Location location) {
 	 * accelerated writing.
 	 *
 	 * @param handle the handle to wrap
+	 * @return the handle wrapped in a write-only buffer or {@code null} if the
+	 *         provided handle is {@code null}
 	 * @see WriteBufferDataHandle#WriteBufferDataHandle(DataHandle)
 	 */
 	default DataHandle<Location> writeBuffer(final DataHandle<Location> handle) {