com.github.aliteralmind.codelet.util

Class JavaDocUtil

java.lang.Object

com.github.aliteralmind.codelet.util.JavaDocUtil

public class JavaDocUtil
extends Object

Get urls to function, class, and object targets.

Since:

0.1.0

Author:

Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Method Summary

Methods

Modifier and Type	Method and Description
static StringBuilder	appendClassNameForParams(StringBuilder to_appendTo, Class<?>[] classes, VarArgs var_args) Append the comma-separated list of JavaDoc parameters for a method or constructor.
static StringBuilder	appendUrlToClass(StringBuilder to_appendTo, String url_toDocRoot, Class<?> target) Append the url to a class.
static StringBuilder	appendUrlToConstructor(StringBuilder to_appendTo, String url_toDocRoot, Constructor<?> target) Append the url to a constructor.
static StringBuilder	appendUrlToField(StringBuilder to_appendTo, String url_toDocRoot, Field target) Append the url to a field.
static StringBuilder	appendUrlToMethod(StringBuilder to_appendTo, String url_toDocRoot, Method target) Append the url to a function.
static String	getClassNameForParams(Class<?>[] classes, VarArgs var_args) Append the comma-separated list of JavaDoc parameters for a method or constructor.
static String	getEllipsisArrayLastParam(Class<?> cls) For the final parameter in a variable-argument method or constructor, that is known to be an array-ellipsis ("..."), get its JavaDoc-url parameter name.
static String	getRelativeUrlToDocRoot(String package_containingLink) Get the url from a link-source file's package to doc-root.
static String	getUrlToClass(String url_toDocRoot, Class<?> target) Get the url to a class.
static String	getUrlToClassViaDocRoot(String url_toDocRoot, Class<?> target) Get the url from a link-source to the target class file.
static String	getUrlToConstructor(String url_toDocRoot, Constructor target) Get the url to a constructor.
static String	getUrlToField(String url_toDocRoot, Field target) Get the url to a field.
static String	getUrlToMethod(String url_toDocRoot, Method target) Get the url to a function.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getUrlToClass

public static final String getUrlToClass(String url_toDocRoot,
                   Class<?> target)

Get the url to a class.

Returns:

appendUrlToClass((new StringBuilder()), url_toDocRoot, target).toString()

appendUrlToClass

public static final StringBuilder appendUrlToClass(StringBuilder to_appendTo,
                             String url_toDocRoot,
                             Class<?> target)

Append the url to a class.

Parameters:

to_appendTo - May not be null.

url_toDocRoot - The url to {@docRoot} for the link target-file. Which must end with a slash "/", and should not be null.. This is also the directory in which the package-list files exists. For local files, this is a relative directory (such as "../../") otherwise this is the full url to the external doc-root directory.

target - May not be null.

Returns:

to_appendTo.append(url_toDocRoot).
append(target.getName.replace(".", "/")).append(".html")

See Also:

getUrlToClass(String, Class)

getUrlToConstructor

public static final String getUrlToConstructor(String url_toDocRoot,
                         Constructor target)

Get the url to a constructor.

Returns:

appendUrlToConstructor((new StringBuilder()), url_toDocRoot, target).toString()

appendUrlToConstructor

public static final StringBuilder appendUrlToConstructor(StringBuilder to_appendTo,
                                   String url_toDocRoot,
                                   Constructor<?> target)

Append the url to a constructor.

Parameters:

to_appendTo - May not be null.

url_toDocRoot - The url to {@docRoot} for the link target-file. Which must end with a slash "/", and should not be null.. This is also the directory in which the package-list files exists. For local files, this is a relative directory (such as "../../") otherwise this is the full url to the external doc-root directory.

target - May not be null.

Returns:

to_appendTo

See Also:

getUrlToConstructor, appendUrlToMethod, appendUrlToClass, appendClassNameForParams

getUrlToMethod

public static final String getUrlToMethod(String url_toDocRoot,
                    Method target)

Get the url to a function.

Returns:

appendUrlToConstructor((new StringBuilder()), url_toDocRoot, target).toString()

appendUrlToMethod

public static final StringBuilder appendUrlToMethod(StringBuilder to_appendTo,
                              String url_toDocRoot,
                              Method target)

Append the url to a function.

Example

Source code

   import  com.github.aliteralmind.codelet.util.JavaDocUtil;
   import  java.lang.reflect.Method;
   import  java.lang.reflect.Constructor;
   import  com.github.xbn.lang.reflect.Declared;
   import  com.github.xbn.lang.reflect.ReflectRtxUtil;

public class FunctionConstructorJavaDocLink  {
   public static final void main(String[] ignored)  {
      testConstructor();
      testConstructor(String.class, int[].class, int[].class);
      testMethod(int.class);
      testMethod(String.class, int[].class);
   }

   private static final void testConstructor(Class<?>... param_types)  {
      Constructor c = ReflectRtxUtil.getConstructor(
         FunctionConstructorJavaDocLink.class, Declared.NO, null,
         (Class<?>[])param_types);
      System.out.println(JavaDocUtil.getUrlToConstructor("../", c));
   }

   private static final void testMethod(Class<?>... param_types)  {
      Method m = ReflectRtxUtil.getMethod(FunctionConstructorJavaDocLink.class,
         "doSomething", Declared.NO, null, (Class<?>[])param_types);
      System.out.println(JavaDocUtil.getUrlToMethod("../../", m));
   }

   public FunctionConstructorJavaDocLink()  {
   }
   public FunctionConstructorJavaDocLink(String s, int[] ai, int... ai2)  {
   }
   public void doSomething(int i)  {
   }
   public void doSomething(String s, int[] ai)  {
   }
}

Output:

../com/github/aliteralmind/codelet/examples/util/FunctionConstructorJavaDocLink.html#FunctionConstructorJavaDocLink()
../com/github/aliteralmind/codelet/examples/util/FunctionConstructorJavaDocLink.html#FunctionConstructorJavaDocLink(java.lang.String, int[], int...)
../../com/github/aliteralmind/codelet/examples/util/FunctionConstructorJavaDocLink.html#doSomething(int)
../../com/github/aliteralmind/codelet/examples/util/FunctionConstructorJavaDocLink.html#doSomething(java.lang.String, int[])

Parameters:

to_appendTo - May not be null.

url_toDocRoot - The url to {@docRoot} for the link target-file. Which must end with a slash "/", and should not be null.. This is also the directory in which the package-list files exists. For local files, this is a relative directory (such as "../../") otherwise this is the full url to the external doc-root directory.

target - May not be null.

Returns:

to_appendTo

See Also:

getUrlToMethod, appendUrlToMethod, appendUrlToClass, appendClassNameForParams

getUrlToField

public static final String getUrlToField(String url_toDocRoot,
                   Field target)

Get the url to a field.

Returns:

appendUrlToField((new StringBuilder()), url_toDocRoot, target).toString()

appendUrlToField

public static final StringBuilder appendUrlToField(StringBuilder to_appendTo,
                             String url_toDocRoot,
                             Field target)

Append the url to a field.

Returns:

appendUrlToClass(to_appendTo, url_toDocRoot, target.getDeclaringClass()).
append("#").append(target.Field#getName())

See Also:

getUrlToField(String, Field)

getRelativeUrlToDocRoot

public static final String getRelativeUrlToDocRoot(String package_containingLink)

Get the url from a link-source file's package to doc-root.

Returns:

packageElementMtchr.reset(package_containingLink).replaceAll("../")
Where packageElementMtchr is initalized to
Pattern.compile(JavaRegexes.IDENTIFIER + "\\.?").matcher("")

getUrlToClassViaDocRoot

public static final String getUrlToClassViaDocRoot(String url_toDocRoot,
                             Class<?> target)

Get the url from a link-source to the target class file. This always goes entirely down to {@docRoot}, and then back to the target file.

Parameters:

url_toDocRoot - The url to {@docRoot} for the link target-file. Which must end with a slash "/", and should not be null.. This is also the directory in which the package-list files exists. For local files, this is a relative directory (such as "../../") otherwise this is the full url to the external doc-root directory.

target - May not be null.

Returns:

packageElementMtchr.reset(target.getName()).replaceAll("../")
Where packageElementMtchr is initalized to
Pattern.compile(".", Pattern.LITERAL).matcher("")

getEllipsisArrayLastParam

public static final String getEllipsisArrayLastParam(Class<?> cls)

For the final parameter in a variable-argument method or constructor, that is known to be an array-ellipsis ("..."), get its JavaDoc-url parameter name.

Example

Source code

   import  com.github.aliteralmind.codelet.util.JavaDocUtil;
public class JavaDocUtilGetEllipsisArrayLastParamXmpl  {
   public static final void main(String[] ignored)  {
      try  {
         System.out.print("int: ");
         JavaDocUtil.getEllipsisArrayLastParam(int.class);
      }  catch(IllegalArgumentException iax)  {
         System.out.println(iax);
      }
      System.out.println("int[]: " + JavaDocUtil.getEllipsisArrayLastParam(int[].class));
      System.out.println("int[][]: " + JavaDocUtil.getEllipsisArrayLastParam(int[][].class));
      System.out.println("String[]: " + JavaDocUtil.getEllipsisArrayLastParam(String[].class));
      System.out.println("String[][]: " + JavaDocUtil.getEllipsisArrayLastParam(String[][].class));
   }
}

Output:

int: java.lang.IllegalArgumentException: cls.isArray() is false.
int[]: int...
int[][]: int[]...
String[]: java.lang.String...
String[][]: java.lang.String[]...

Parameters:

cls - May not be null.

Returns:

The canonical class name, where the final array indicator ("[]") is replaced with an ellipsis ("...").

Throws:

IllegalArgumentException - If cls is not an array.

See Also:

appendClassNameForParams(StringBuilder, Class[], VarArgs), Class#getCanonicalName(), Class.getCanonicalName()

getClassNameForParams

public static final String getClassNameForParams(Class<?>[] classes,
                           VarArgs var_args)

Append the comma-separated list of JavaDoc parameters for a method or constructor.

Returns:

appendClassNameForParams((new StringBuilder()), classes, is_varArgs).toString()

appendClassNameForParams

public static final StringBuilder appendClassNameForParams(StringBuilder to_appendTo,
                                     Class<?>[] classes,
                                     VarArgs var_args)

Append the comma-separated list of JavaDoc parameters for a method or constructor. This does not include the surrounding parentheses.

This appends the canonical name of each class. If is_varArgs is true, the final parameter is output with getEllipsisArrayLastParam.

Parameters:

to_appendTo - May not be null.

classes - May not be null, and is_varArgs is true, the final element must be an array (and classes.length should be non-empty).

var_args - If YES, this is a variable-argument method or constructor, meaning the final parameter is an ellipsis array: "...". This parameter value may not be null.

Returns:

to_appendTo

See Also:

getClassNameForParams(Class[], VarArgs), appendUrlToConstructor, appendUrlToMethod, lang.reflect.ReflectRtxUtil#appendClassNames