Fix #24: Fix scaladoc (#60)

* Fixed all documentation warnings due to link problems

sconfig/jvm/src/main/scala/org/ekrich/config/ConfigBeanFactory.scala

@@ -3,14 +3,14 @@ package org.ekrich.config
 import org.ekrich.config.impl.ConfigBeanImpl
 
 /**
- * Factory for automatically creating a Java class from a [[Config]].
- * See [[ConfigBeanFactory.create(Config,Class)]].
+ * Factory for automatically creating a Java class from a {@link Config}.
+ * See {@link ConfigBeanFactory#create}.
  *
  * @since 1.3.0
  */
 object ConfigBeanFactory {
   /**
-   * Creates an instance of a class, initializing its fields from a [[Config]].
+   * Creates an instance of a class, initializing its fields from a {@link Config}.
    *
    * Example usage:
    *
@@ -20,8 +20,8 @@ object ConfigBeanFactory {
    * }}}
    *
    * The Java class should follow JavaBean conventions. Field types
-   * can be any of the types you can normally get from a [[Config]],
-   * including `java.time.Duration` or [[ConfigMemorySize]].
+   * can be any of the types you can normally get from a {@link Config},
+   * including `java.time.Duration` or {@link ConfigMemorySize}.
    * Fields may also be another JavaBean-style
    * class.
    *
@@ -34,12 +34,12 @@ object ConfigBeanFactory {
    * @param clazz class to be instantiated
    * @param <T> the type of the class to be instantiated
    * @return an instance of the class populated with data from the config
-   * @throws [[ConfigException#BadBean]]
+   * @throws ConfigException#BadBean
    *     If something is wrong with the JavaBean
-   * @throws [[ConfigException#ValidationFailed]]
+   * @throws ConfigException#ValidationFailed
    *     If the config doesn't conform to the bean's implied schema
    * @throws ConfigException
-   *     Can throw the same exceptions as the getters on `Config`
+   *     Can throw the same exceptions as the getters on {@link Config}
    */
   def create[T](config: Config, clazz: Class[T]): T =
     ConfigBeanImpl.createInternal(config, clazz)

sconfig/shared/src/main/scala/org/ekrich/config/ConfigException.scala

@@ -278,7 +278,7 @@ object ConfigException {
 
   /**
    * Exception indicating that a substitution did not resolve to anything.
-   * Thrown by {@link Config#resolve}.
+   * Thrown by [[Config!.resolve()* resolve()]].
    */
   @SerialVersionUID(1L)
   class UnresolvedSubstitution(
@@ -296,10 +296,10 @@ object ConfigException {
   /**
    * Exception indicating that you tried to use a function that requires
    * substitutions to be resolved, but substitutions have not been resolved
-   * (that is, {@link Config#resolve} was not called). This is always a bug in
-   * either application code or the library; it's wrong to write a handler for
-   * this exception because you should be able to fix the code to avoid it by
-   * adding calls to {@link Config#resolve}.
+   * (that is, [[Config!.resolve()* resolve()]] was not called). This is always
+   * a bug in either application code or the library; it's wrong to write a
+   * handler for this exception because you should be able to fix the code to
+   * avoid it by adding calls to [[Config!.resolve()* resolve()]].
    */
   @SerialVersionUID(1L)
   class NotResolved(message: String, cause: Throwable)

sconfig/shared/src/main/scala/org/ekrich/config/ConfigIncludeContext.scala

@@ -36,7 +36,7 @@ trait ConfigIncludeContext {
 
   /**
    * Parse options to use (if you use another method to get a
-   * {@link ConfigParseable} then use {@link ConfigParseable#options()}
+   * {@link ConfigParseable} then use {@link ConfigParseable#options}
    * instead though).
    *
    * @return the parse options

sconfig/shared/src/main/scala/org/ekrich/config/ConfigList.scala

@@ -11,14 +11,14 @@ import java.{util => ju}
  *
  * <p>
  * {@code ConfigList} implements {@code java.util.List<ConfigValue>} so you can
- * use it like a regular Java list. Or call {@link #unwrapped()} to unwrap the
+ * use it like a regular Java list. Or call {@link #unwrapped} to unwrap the
  * list elements into plain Java values.
  *
  * <p>
  * Like all {@link ConfigValue} subtypes, {@code ConfigList} is immutable. This
  * makes it threadsafe and you never have to create "defensive copies." The
- * mutator methods from {@link java.util.List} all throw
- * {@link java.lang.UnsupportedOperationException}.
+ * mutator methods from `java.util.List` all throw
+ * `java.lang.UnsupportedOperationException`.
  *
  * <p>
  * The {@link ConfigValue#valueType} method on a list returns
@@ -37,7 +37,7 @@ trait ConfigList extends ju.List[ConfigValue] with ConfigValue {
    * Recursively unwraps the list, returning a list of plain Java values such
    * as Integer or String or whatever is in the list.
    *
-   * @return a {@link java.util.List} containing plain Java objects
+   * @return a `java.util.List` containing plain Java objects
    */
   override def unwrapped: ju.List[AnyRef]
   override def withOrigin(origin: ConfigOrigin): ConfigList

sconfig/shared/src/main/scala/org/ekrich/config/ConfigLoadingStrategy.scala

@@ -2,7 +2,8 @@ package org.ekrich.config
 
 /**
  * This method allows you to alter default config loading strategy for all the code which
- * calls one of the methods, e.g. [[ConfigFactory.load(String)]]
+ * calls one of the methods, e.g.
+ * [[ConfigFactory$.load(resourceBasename:String)* ConfigFactory.load(String)]]
  *
  * Usually you don't have to implement this interface but it may be required
  * when you fixing a improperly implemented library with unavailable source code.

sconfig/shared/src/main/scala/org/ekrich/config/ConfigMemorySize.scala

@@ -5,8 +5,8 @@ package org.ekrich.config
 
 /**
  * An immutable class representing an amount of memory.  Use
- * static factory methods such as {@link
- * ConfigMemorySize#ofBytes(long)} to create instances.
+ * static factory methods such as
+ * {@link ConfigMemorySize#ofBytes} to create instances.
  *
  * @since 1.3.0
  */

sconfig/shared/src/main/scala/org/ekrich/config/ConfigObject.scala

@@ -11,27 +11,27 @@ import java.{util => ju}
  *
  * <p>
  * An object may also be viewed as a {@link Config} by calling
- * {@link ConfigObject#toConfig()}.
+ * {@link ConfigObject#toConfig}.
  *
  * <p>
  * {@code ConfigObject} implements {@code java.util.Map<String, ConfigValue>} so
- * you can use it like a regular Java map. Or call {@link #unwrapped()} to
+ * you can use it like a regular Java map. Or call {@link #unwrapped} to
  * unwrap the map to a map with plain Java values rather than
  * {@code ConfigValue}.
  *
  * <p>
  * Like all {@link ConfigValue} subtypes, {@code ConfigObject} is immutable.
  * This makes it threadsafe and you never have to create "defensive copies." The
- * mutator methods from {@link java.util.Map} all throw
- * {@link java.lang.UnsupportedOperationException}.
+ * mutator methods from `java.util.Map` all throw
+ * `java.lang.UnsupportedOperationException`.
  *
  * <p>
  * The {@link ConfigValue#valueType} method on an object returns
  * {@link ConfigValueType#OBJECT}.
  *
  * <p>
  * In most cases you want to use the {@link Config} interface rather than this
- * one. Call {@link #toConfig()} to convert a {@code ConfigObject} to a
+ * one. Call {@link #toConfig} to convert a {@code ConfigObject} to a
  * {@code Config}.
  *
  * <p>
@@ -41,13 +41,14 @@ import java.{util => ju}
  * {@code Config} is a one-level map from paths to values.
  *
  * <p>
- * Use {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath} to convert
+ * Use [[ConfigUtil$.joinPath(elements:String*)* ConfigUtil.joinPath(String*)]]
+ * and [[ConfigUtil$.splitPath ConfigUtil.splitPath(String)]] to convert
  * between path expressions and individual path elements (keys).
  *
  * <p>
  * A {@code ConfigObject} may contain null values, which will have
- * {@link ConfigValue#valueType()} equal to {@link ConfigValueType#NULL}. If
- * {@link ConfigObject#get(Object)} returns Java's null then the key was not
+ * {@link ConfigValue#valueType} equal to {@link ConfigValueType#NULL}. If
+ * {@link ConfigObject#get} returns Java's null then the key was not
  * present in the parsed file (or wherever this value tree came from). If
  * {@code get("key")} returns a {@link ConfigValue} with type
  * {@code ConfigValueType#NULL} then the key was set to null explicitly in the
@@ -74,9 +75,10 @@ trait ConfigObject extends ConfigValue with ju.Map[String, ConfigValue] {
    * Recursively unwraps the object, returning a map from String to whatever
    * plain Java values are unwrapped from the object's values.
    *
-   * @return a {@link java.util.Map} containing plain Java objects
+   * @return a `java.util.Map` containing plain Java objects
    */
   override def unwrapped: ju.Map[String, AnyRef]
+
   override def withFallback(other: ConfigMergeable): ConfigObject
 
   /**
@@ -115,7 +117,7 @@ trait ConfigObject extends ConfigValue with ju.Map[String, ConfigValue] {
    * Returns a {@code ConfigObject} based on this one, but with the given key
    * set to the given value. Does not modify this instance (since it's
    * immutable). If the key already has a value, that value is replaced. To
-   * remove a value, use {@link ConfigObject#withoutKey(String)}.
+   * remove a value, use {@link ConfigObject#withoutKey}.
    *
    * @param key
    *            key to add
@@ -124,5 +126,6 @@ trait ConfigObject extends ConfigValue with ju.Map[String, ConfigValue] {
    * @return the new instance with the new map entry
    */
   def withValue(key: String, value: ConfigValue): ConfigObject
+
   override def withOrigin(origin: ConfigOrigin): ConfigObject
 }

sconfig/shared/src/main/scala/org/ekrich/config/ConfigOriginFactory.scala

@@ -8,15 +8,15 @@ import org.ekrich.config.impl.ConfigImpl
  * [[ConfigOrigin]]s are automatically created when you
  * call other API methods to get a [[ConfigValue]] or [[Config]].
  * But you can also set the origin of an existing [[ConfigValue]], using
- * [[ConfigValue.withOrigin(ConfigOrigin)]].
+ * [[ConfigValue#withOrigin ConfigValue.withOrigin(ConfigOrigin)]].
  *
  * @since 1.3.0
  */
 object ConfigOriginFactory {
   /**
    * Returns the default origin for values when no other information is
    * provided. This is the origin used in
-   * [[ConfigValueFactory.fromAnyRef(Object)]].
+   * [[ConfigValueFactory$.fromAnyRef(obj:Object)* ConfigValueFactory.fromAnyRef(Object)]].
    *
    * @since 1.3.0
    * @return the default origin

sconfig/shared/src/main/scala/org/ekrich/config/ConfigParseOptions.scala

@@ -186,8 +186,8 @@ final class ConfigParseOptions private (
 
   /**
    * Appends a {@link ConfigIncluder} which customizes how
-   * includes are handled.  To append, the library calls {@link
-   * ConfigIncluder#withFallback} on the existing includer.
+   * includes are handled.  To append, the library calls
+   * {@link ConfigIncluder#withFallback} on the existing includer.
    *
    * @param includer the includer to append (may not be null)
    * @return new version of the parse options with different includer

sconfig/shared/src/main/scala/org/ekrich/config/ConfigRenderOptions.scala

@@ -6,7 +6,7 @@ package org.ekrich.config
 /**
  * <p>
  * A set of options related to rendering a {@link ConfigValue}. Passed to
- * {@link ConfigValue#render(ConfigRenderOptions)}.
+ * [[ConfigValue!.render(options:org\.ekrich\.config\.ConfigRenderOptions)* ConfigValue.render(ConfigRenderOptions)]].
  *
  * <p>
  * Here is an example of creating a {@code ConfigRenderOptions}:
@@ -69,7 +69,7 @@ final class ConfigRenderOptions private (
    * comments might tell you which file a setting comes from.
    *
    * <p>
-   * {@code setOriginComments()} controls only these autogenerated
+   * {@code setOriginComments(Boolean)} controls only these autogenerated
    * "origin of this setting" comments, to toggle regular comments use
    * {@link ConfigRenderOptions#setComments}.
    *
@@ -113,8 +113,8 @@ final class ConfigRenderOptions private (
   /**
    * Returns options with JSON toggled. JSON means that HOCON extensions
    * (omitting commas, quotes for example) won't be used. However, whether to
-   * use comments is controlled by the separate {@link #setComments(boolean)}
-   * and {@link #setOriginComments(boolean)} options. So if you enable
+   * use comments is controlled by the separate {@link #setComments}
+   * and {@link #setOriginComments} options. So if you enable
    * comments you will get invalid JSON despite setting this to true.
    *
    * @param value

sconfig/shared/src/main/scala/org/ekrich/config/ConfigResolveOptions.scala

@@ -9,7 +9,7 @@ package org.ekrich.config
  * [[https://github.com/ekrich/sconfig/blob/master/HOCON.md">HOCON spec]].
  * <p>
  * Typically this class would be used with the method
- * {@link Config#resolve(ConfigResolveOptions)}.
+ * [[Config!.resolve(options:org\.ekrich\.config\.ConfigResolveOptions)* Config.resolve(ConfigResolveOptions)]].
  * <p>
  * This object is immutable, so the "setters" return a new object.
  * <p>
@@ -81,8 +81,9 @@ final class ConfigResolveOptions private (
    * Returns options with "allow unresolved" set to the given value. By
    * default, unresolved substitutions are an error. If unresolved
    * substitutions are allowed, then a future attempt to use the unresolved
-   * value may fail, but {@link Config#resolve(ConfigResolveOptions)} itself
-   * will not throw.
+   * value may fail, but
+   * [[Config!.resolve(options:org\.ekrich\.config\.ConfigResolveOptions)* Config.resolve(ConfigResolveOptions)]]
+   * itself will not throw.
    *
    * @param value
    *            true to silently ignore unresolved substitutions.

sconfig/shared/src/main/scala/org/ekrich/config/ConfigResolver.scala

@@ -11,8 +11,9 @@ package org.ekrich.config
 trait ConfigResolver {
   /**
    * Returns the value to substitute for the given unresolved path. To get the
-   * components of the path use {@link ConfigUtil#splitPath(String)}. If a
-   * non-null value is returned that value will be substituted, otherwise
+   * components of the path use
+   * [[ConfigUtil$.splitPath ConfigUtil.splitPath(String)]].
+   * If a non-null value is returned that value will be substituted, otherwise
    * resolution will continue to consider the substitution as still
    * unresolved.
    *

sconfig/shared/src/main/scala/org/ekrich/config/ConfigValue.scala

@@ -37,7 +37,7 @@ trait ConfigValue extends ConfigMergeable {
   /**
    * Returns the value as a plain Java boxed value, that is, a {@code String},
    * {@code Number}, {@code Boolean}, {@code Map<String,Object>},
-   * {@code List<Object>}, or {@code null}, matching the {@link #valueType()}
+   * {@code List<Object>}, or {@code null}, matching the {@link #valueType}
    * of this {@code ConfigValue}. If the value is a {@link ConfigObject} or
    * {@link ConfigList}, it is recursively unwrapped.
    *
@@ -51,7 +51,8 @@ trait ConfigValue extends ConfigMergeable {
    * whitespace.
    *
    * <p>
-   * If the config value has not been resolved (see {@link Config#resolve}),
+   * If the config value has not been resolved
+   * (see [[Config!.resolve()* Config.resolve()]]),
    * it's possible that it can't be rendered as valid HOCON. In that case the
    * rendering should still be useful for debugging but you might not be able
    * to parse it. If the value has been resolved, it will always be parseable.
@@ -68,7 +69,8 @@ trait ConfigValue extends ConfigMergeable {
    * Renders the config value to a string, using the provided options.
    *
    * <p>
-   * If the config value has not been resolved (see {@link Config#resolve}),
+   * If the config value has not been resolved
+   * (see [[[Config!.resolve()* Config.resolve()]]),
    * it's possible that it can't be rendered as valid HOCON. In that case the
    * rendering should still be useful for debugging but you might not be able
    * to parse it. If the value has been resolved, it will always be parseable.
@@ -84,11 +86,12 @@ trait ConfigValue extends ConfigMergeable {
    * @return the rendered value
    */
   def render(options: ConfigRenderOptions): String
+
   override def withFallback(other: ConfigMergeable): ConfigValue
 
   /**
    * Places the value inside a {@link Config} at the given path. See also
-   * {@link ConfigValue#atKey(String)}.
+   * {@link ConfigValue#atKey}.
    *
    * @param path
    *            path to store this value at.
@@ -99,7 +102,7 @@ trait ConfigValue extends ConfigMergeable {
 
   /**
    * Places the value inside a {@link Config} at the given key. See also
-   * {@link ConfigValue#atPath(String)}.
+   * {@link ConfigValue#atPath}.
    *
    * @param key
    *            key to store this value at.