HOW TO: Generate docs for your extensions [Java/JAR]

Hi :slightly_smiling_face:,
Many extension developers spend a lot of time in making extensions but even after that they need to work on documentation which is sometimes a big job.
So, this tutorial will surely help you, if you are one of them. :wink:
Let's get started.

1.Get component.json file

  • Open aix using any Zip software
  • Navigate to package name until you saw some files
  • Double click on component.json file and copy contents of it

2.Open any Java IDE [Intellij IDEA or Eclipse](Shouldn't be online one)

  • Create a class
  • Add these imports
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import org.json.simple.parser.JSONParser;
import org.json.simple.parser.ParseException;

import java.awt.*;
import java.awt.datatransfer.Clipboard;
import java.awt.datatransfer.StringSelection;
  • Add main method
  • Add following variables
public static String docs = "component.json content";
public static StringBuilder builder = new StringBuilder();
  • Add following code in main method
       try {
            addEvents();
            addMethods();
            addProperties();
            StringSelection stringSelection = new StringSelection(builder.toString());
            Clipboard clipboard = Toolkit.getDefaultToolkit().getSystemClipboard();
            clipboard.setContents(stringSelection, null);
        } catch (ParseException e) {
            e.printStackTrace();
        }
  • Add following methods
public void addEvents() throws ParseException {
        JSONObject object = (JSONObject) new JSONParser().parse(text);
        JSONArray array = (JSONArray) object.get("events");
        if (!array.isEmpty()) {
            for (Object item : array) {
                JSONObject ob = (JSONObject) item;
                builder.append("> <h3>");
                builder.append(ob.get("name"));
                builder.append("</h3>");
                builder.append(ob.get("description"));
                JSONArray arr = (JSONArray) ob.get("params");
                if (!arr.isEmpty()) {
                    builder.append("\n" +
                            "Params           |  []()       \n" +
                            "---------------- | ------- \n" +
                            "\n");
                    for (Object value : arr) {
                        JSONObject o = (JSONObject) value;
                        builder.append("```` ").append(o.get("name")).append(" | ");
                        builder.append(o.get("type")).append("````\n");
                    }
                }
                builder.append("\n ____________________________________\n\n");
            }
        }
    }
    public void addMethods() throws ParseException {
        JSONObject object = (JSONObject) new JSONParser().parse(text);
        JSONArray array = (JSONArray) object.get("methods");
        if (!array.isEmpty()) {
            for (Object item : array) {
                JSONObject ob = (JSONObject) item;
                builder.append("> <h3>");
                builder.append(ob.get("name"));
                builder.append("</h3>");
                builder.append(ob.get("description"));
                JSONArray arr = (JSONArray) ob.get("params");
                if (!arr.isEmpty()) {
                    builder.append("\n" +
                            "Params           |  []()       \n" +
                            "---------------- | ------- \n" +
                            "\n");
                    for (Object value : arr) {
                        JSONObject o = (JSONObject) value;
                        builder.append("```` ").append(o.get("name")).append(" | ");
                        builder.append(o.get("type")).append("````<br>\n");
                    }
                }
                if (ob.containsKey("returnType")){
                    builder.append("\n<i>Return type : ").append(ob.get("returnType")).append("</i>\n");
                }
                builder.append("\n____________________________________\n\n");
            }
        }
    }
    public void addProperties() throws ParseException {
        JSONObject object = (JSONObject) new JSONParser().parse(text);
        JSONArray array = (JSONArray) object.get("blockProperties");
        if (!array.isEmpty()) {
            for (Object item : array) {
                JSONObject ob = (JSONObject) item;
                builder.append("> <h3>");
                builder.append(ob.get("name"));
                builder.append("</h3>");
                builder.append(ob.get("description"));
                if (ob.containsKey("rw")){
                    builder.append("\n<i>Property Type : ").append(ob.get("rw")).append("</i>");
                }
                if (ob.containsKey("type")){
                    builder.append("<br><i>Accepts : ").append(ob.get("type")).append("</i>");
                }
                builder.append("\n____________________________________\n\n");
            }
        }
    }

Now run the method/class once and docs will get copied to clipboard. :smiley:

How it looks ->

Method/Event name

Description

Params

param1 | type1
param2 | type2

7 Likes

Great guide! :grinning: Useful to me!

Nice guide @vknow360
Also there is a generator by @Ct_tricks
https://cttricks.com/extension-docs/index.php

There are many cons for not choosing that.

cool guide !

Nice Guide :innocent: :kissing_heart:

1 Like

Meanwhile you can just run this jar:


ChangeLog Version 2

  • Tool is now compatible with Rush which does generate component.json file
  • Now you can drag and drop aix file (Any other file will not get dropped)
  • Errors are shown in a dialog
  • Minor UI improvements, like file path label is now responsive
4 Likes

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

Now Open Source. :+1: