Github user mike-jumper commented on a diff in the pull request:
https://github.com/apache/guacamole-client/pull/271#discussion_r181179068
--- Diff:
guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractAuthenticationProvider.java
---
@@ -0,0 +1,157 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.guacamole.net.auth;
+
+import org.apache.guacamole.GuacamoleException;
+
+/**
+ * Base implementation of AuthenticationProvider which provides default
+ * implementations of most functions. Implementations must provide their
+ * own {@link #getIdentifier()}, but otherwise need only override an
implemented
+ * function if they wish to actually implement the functionality defined
for
+ * that function by the AuthenticationProvider interface.
+ */
+public abstract class AbstractAuthenticationProvider implements
AuthenticationProvider {
+
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns <tt>null</tt>.
Implementations that
--- End diff --
> I see some of these HTML tags in a few other Java classes, but definitely
does not seem to be widely used throughout JavaDoc comments in the Guacamole
code. Did you intend to put these here?
Yep. This is intentional. JavaDoc uses a subset of HTML for formatting.
> Is that something you want to start using, or something that crept in
from an IDE?
We probably should start using such formatting as applicable. The
additional formatting makes the documentation significantly more readable, and
there are more than a few comments in older code which rely on my erroneous
impression that blank lines would imply a new paragraph (JavaDoc actually just
ignores those blanks).
> Similarly, the `{@inheritDoc}` directive doesn't seem to show up anywhere
else - again, something/new intentional, or something that slipped by?
Definitely intentional.
It is normally not necessary, as JavaDoc automatically pulls in the
documentation for overridden methods, but it's necessary here where I'm
intending to add a note regarding implementation without replacing (or manually
duplicating) the existing documentation.
Including `{@inheritDoc}` like this pulls in the original documentation for
the function, all parameters, the return value, throws, etc., while also
appending the text below, which in this case are implementation details.
I looked to the main Java source for examples on how such default
implementations should be documented, as I recalled that `AbstractMap` had
similar needs for its `putAll()` implementation ([noting that it relies on
`put()`](https://docs.oracle.com/javase/7/docs/api/java/util/AbstractMap.html#putAll(java.util.Map))):
/**
* {@inheritDoc}
*
* <p>This implementation iterates over the specified map's
* <tt>entrySet()</tt> collection, and calls this map's <tt>put</tt>
* operation once for each entry returned by the iteration.
*
* <p>Note that this implementation throws an
* <tt>UnsupportedOperationException</tt> if this map does not support
* the <tt>put</tt> operation and the specified map is nonempty.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
*/
public void putAll(Map<? extends K, ? extends V> m) {
for (Map.Entry<? extends K, ? extends V> e : m.entrySet())
put(e.getKey(), e.getValue());
}
---
