Annotation Type LinkJavaSource

  • @Retention(SOURCE)
@Target({TYPE,FIELD,CONSTRUCTOR,METHOD})
@Repeatable(Torello.JavaDoc.hidden.LJSRepeatable.class)
public @interface LinkJavaSource
    LinkJavaSource Annotation.

    This Annotation is a feature of the Java-Doc Upgrader that allows a user to insert HTML Anchor-Links to external / secondary HiLited-HTML Source-Code Files. These links can be specified by annotating a method, field, constructor, etc... (an Entity) with this Annotation. When a Detail-Entity is annotated with this Annotation, the "@LinkJavaSource-Annotation", the Java-Doc Upgrader Tool will generate an "External-Java" Button (HTML Anchor-Link) that connects a User to a Hi-Lited HTML Source-Code File that is named by the handle element.

    The user has the option of specifying, explicity, line-number within that '.java' Source-File. There are a series of additional Annotation-Elements which provide a seamless way of expressing, exactly, a specific method, field, constructor, annotation-element or enum-constant (These are the 5 available "Entities" of a Java-Doc Web-Page)

    The only "Required Annotation Element" for this annotation is the handle element. This is required because it is how a user is expected to specify the actual Source-Code file that is expected to be linked to the Detail-Entity that is being annotated. The remainder of the available elements are all "Optional Annotation Elements" - meaning that the user does not have to provide values for these "parameters" when using this annotation.

    The following are the two variants for using this Documentation-Upgrade Annotation:

    1. When specifying a File Handle (the only required annotation element), the Upgrader Tool will generate a simple link to the top of the highlighted source file.

    2. In addition to the File Handle, users may provide any combination of the following optional annotation elements to specify a more precise location within the source file:

      entity - the type of entity (e.g., METHOD, FIELD, etc.).
      name - the name of the method, field, or constructor.
      paramCount - the number of parameters.
      paramNames - the names of the parameters.
      paramTypesJOW - the types of the parameters.
      typeName - the full name of an inner or auxiliary type.


      Providing any of these elements allows the Upgrader Tool to parse the Java file's Abstract Syntax Tree (AST) to identify the exact line number and create a link that directs the browser to that precise location. However, if the source file is short, parsing may not be necessary, and the link will default to the top of the file. For larger files, it's recommended to specify a location to enhance navigation. This feature improves the user experience by helping "My Users" guide "His Users" to the right part of the code.



    @LinkJavaSource Example
    The following is an example of the use of this Annotation. The following example will attempt to elucidate

    Example:
    /**
 * This is an example of linking a Java Source-File, and providing the name of a method.
 * @return The value {@code '0'}.
 */
@LinkJavaSource(handle="FileHandle01", name="allFieldDetails", entity=FIELD)
public int mainExample()
{ return 0; }

    • handle: The User-Provided value 'FileHandle01' specifies a Syntax-HiLited '.java' Source-File which has been assiged the moniker (handle) 'FileHandle01'

    • name: The assigned value 'allFieldDetails' states that this particular use of the @LinkJavaSource-Annotation is requesting that a field named 'allFieldDetails' be directly linked - explicitly by that field's line-number within the Class' Source-File - to this particular Java-Doc Detail-HTML.

    • entity: The assigned value 'Entity.FIELD' further specifies that the Entity / Member which is being named by this element, the 'name' element, (which, again, is 'allFieldDetails' as explained directly above) is indeed a field contained by the Syntax-HiLited Class JavaDocHTMLFile (rather than, say, a method, an enum-constant, a constructor etc...)


    The Source which is Linked:
    Here is the Source-Code to which this @LinkJavaSource link shall be pointing on the Java-Doc Page which has placed this annotation. Note that it is not mandatory to specify a method, field or constructor when using the @LinkJavaSource annotation. If the specific entity is not named inside the Annotation Elements / Parameters, then the <A HREF='...> which is inserted shall point to directly to the top of the class, interface (the type) etc...

    In the above example, their is actual entity that is named by the annotation. Specifically, the field JavaDocHTMLFile.allFieldDetails is the actual member / entity that the user would like to show-case to his users on this particular Java-Doc File. Note that the HTML <A HREF='...> which is inserted will be to the Hi-Lited Source-Code, rather than the Java-Doc HTML Page.

    Example:
    public final class JavaDocHTMLFile extends ParsedFile implements java.io.Serializable
{
    ... // Much of this Class-Content has been eliminated for brevity.  This class may be viewed
        // in its entirety on the Java-Doc Page within this particular package (Torello.JavaDoc)

    /**
     * This is the list of all fields in the "Field Details", stored as Reflection-HTML
     * instances
     */
    public final ReadOnlyList<ReflHTML<Field>> allFieldDetails;


    The Generated HTML:

    The link which is inserted by this Ugrader-Tool will look as follows. The HTML depiction, directly below contains the inserted HTML. There is an Animated Red-Arrow which is pointing to the button that this Java-Annotation has asked be created. You may click on that Arrow-Button, itself, and your browser will be redirected to a segment of the Hi-Lited Source-Code which has been specified by this Annotation.

    The Text-Label which states, simply, "External-Java" is the purpose of the @LinkJavaSource Annotation. Again, as mentioned earlier, in this particular example, the link will redirect your browser to a Hi-Lited Source-File for the class JavaDocHTMLFile (which is an actual class of the Java-Doc Upgrader-Class).

    Note, Chat-GPT wrote all of the CSS for this entire thing. This is what I said to Mr. GPT and the below hiliting is what it came up with:

    OK, you are thinking "boredom", and I'm trying to think of a giant thing that shoots out rainbows & unicorns.


    • mainExample

      🡅  ⇈  ⮫     ⇐ External-Java:   ⮫ 🗕  🗗  🗖 
      public int mainExample()
      This is an example of linking a secondary or tertiary Hi-Lited Java Source-File, by placing this annotation on this (the primary) method.

      Due to this Annotation-Placement, the Java-HTML Java-Doc Upgrader Tool has inserted a Label (directly above) which says "External-Java", along with an Anchor-Link Button that connects the user to the field which is specified inside the annotation.
      Returns:
      The value '0'.


    HiLiting the File:
    Below is the '.json'-File Object that maps the specified 'handle' (which, as should be obvious by the hiliting below, is 'FileHandle01') - maps that 'handle' to an actual on disk '.java' Source-Code File that needs to be hilited in order for any and all Annotations that are place on your Entities..

    It should also be evident by inspecting the below JSON-Object, that this particular use of the @LinkJavaSource-Annotation has been applied in order to hilite the Java-Doc Upgrader Source-File for the class JavaDocHTMLFile

    This JSON-Object should be placed within any '.json'-File as long as it is located in the directory: [Your Source Packge Dir]/upgrade-files/json-config/link-java-source/

    Any '.json'-Files which are located inside this directory will be parsed by the Upgrader's JSON-Parser, and if they have been properly formatted, the Java-Files which have been specified will by hilited and saved to the appropriate output 'javadoc/' directory.

    Java Script Object Notation (JSON):
    {
    "Handle"        : "FileHandle01",
    "JavaFileName"  : "Torello/JavaDoc/package-source/Reflection HTML/JavaDocHTMLFile.java",
    "Parse"         : true
}

    • Handle: This Json-Property simply informs the Java-Doc Upgrader that this particular Source-Code File should be passed through the Syntax-HiLiter, and saved to the [package-javadoc-dir]/ljs-hilite-files/ directory so that it may be properly linked to this - or any - HTML Detail-Element.

      In order to acheive this, simply place the @LinkJavaSource-Annotation on any Method, Field, Constructor, etc... within your Class and be sure to use the handle="FileHandle01". When the Upgrader runs, it will automatically insert an HTML Link onto annotated HTML-Detail Element for the Java-Doc HTML-Page for that class.

    • JavaFileName: Simply put, the aforementioned 'handle' is, formally, being assigned to the Java Source-Code File 'JavaDocHTMLFile.java'. It is importat to note that this particular file (in this example) is actually one of the Source-Code Files for the Java-HTML Jar-Library. However, it is not a mandatory condition that the named Source-File be a part of your '.jar', Package or Project. Literally any Source-File within the entire File-System can be named for hiliting by the Upgrader's Syntax-HiLiter.

    • Parse: This is an optional Object-Property, and it's Default-Value is actually assigned 'true'. For this reason, generally, if this Json Object-Property is assigned a value at all that value will always be false! (Precisely because it's an optional property, which is by default 'true').

      When using the @LinkJavaSource there may be many Source-Files in which there is no need to actually parse the actual '.java'-Code itself. In fact, the only reason that an actual AST-Parse is ever necessary is if the user would like to name an actual entity (Method, Field, Constructor, etc...) within the Class-File / Source-File so that the explicit line-number within the file may be linked.

      Any Source-File that is short enough such that actual direct Line-Number links would be largely superfluous should use the "Parse": false Object-Property. An AST-Parse does, indeed, consume some cycles - so if it can be avoided, it should be in order to make your buid run faster!

      Again, the actual naming of a Field, Method, Constructor, etc... for linking (using an HTML <A HREF='...>) is of value only if the Source-File, itself, is extremely long and a link to the top of the Source-File would be confusing and unclear! The actual Line-Number Links into the file is is generated by running an AST-Parse of the file, and then identifying the Detail-Entities (Methods, Fields, Constructors, etc...) within that file. Afterwards the explicit Line-Numbers for the Detail-Entity is obtained by querying the com.sun.soure.tree.LineMap class.

      This is a somewhat expensive operation!


    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      String handle
      The String-Value which is provided to this element specifies which HiLited Source-Code File to use for the URL-Link in this <A HREF>-Button.

    • Optional Element Summary

       
      Specify which Source-File to be linked due to this Annotation's Placement
      Modifier and Type Optional Element Description
      Entity entity
      When specifying a Line-Number to use for the link, identifies which kind of Entity is being linked.
      String name
      When specifying a Line-Number to use, identifies the Entity or "Member" Name.
      byte paramCount
      When specifying the Line-Number of either a Method or a Constructor, identifies the number of parameters contained by the Method or Constructor Signature.
      String[] paramNames
      When specifying the Line-Number of either a Method or a Constructor, identifies the names of the parameters accepted by the Method or Constructor.
      String[] paramTypesJOW
      When specifying the Line-Number of either a Method or a Constructor, identifies the Single-Word-Names for the 'types' of the Method's or Constructor's parameters.
      String typeName
      This String may be used to specify an 'Inner-Type', 'Nested-Type' or possibly an 'Auxilliary-Class'.

    • Element Detail

      • handle

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.lang.String handle
        The String-Value which is provided to this element specifies which HiLited Source-Code File to use for the URL-Link in this <A HREF>-Button.

        This must be equal to one of the listed File-Handle's which you have placed inside of your 'upgrade-files/json-config/ExtraJavaHiLiting.json' file.
      Code:
      Exact Element Declaration:
       public String handle();