} elements.
+ */
+ private String linkTypeName(TypeRef type, @Nullable ClassDoc context) {
+ String displayName = escapeHtml(type.name());
+ ResolvedType resolved = resolveTypeUrl(type, context);
+ if (resolved == null || resolved.url() == null) {
+ return Syntax.type(displayName);
+ }
+
+ StringBuilder attribs = new StringBuilder();
+ attribs.append("href=\"").append(resolved.url()).append("\"");
+ if (resolved.isExternal()) {
+ attribs.append(" target=\"_blank\"");
+ attribs.append(" rel=\"noopener noreferrer\"");
+ }
+
+ return Syntax.linkedType(wrapHtmlWithElemAndAttribs(
+ displayName,
+ "a",
+ attribs.toString()
+ ));
+ }
+
+ /** Escapes < and > to HTML entities for safe embedding in HTML code elements. */
+ private String escapeHtml(String text) {
+ return text.replace("<", "<").replace(">", ">");
+ }
+
+ /**
+ * Resolves the URL for a declared type.
+ *
+ * - Checks the internal project index (classByQualifiedName).
+ * - Falls back to the external Javadoc package index.
+ *
+ * Returns {@code null} when no link can be determined.
+ */
+ private ResolvedType resolveTypeUrl(TypeRef type, @Nullable ClassDoc context) {
+ // 1. Internal project class?
+ ClassDoc internal = classByQualifiedName.get(type.qualifiedName());
+ if (internal != null) {
+ return new ResolvedType(type.qualifiedName(), buildLinkUrl(internal, null, context), false);
+ }
+
+ // 2. External Javadoc?
+ String externalUrl = resolveExternalTypeUrl(type.qualifiedName());
+ if (externalUrl != null) {
+ return new ResolvedType(type.qualifiedName(), externalUrl, true);
+ }
+
+ return null;
+ }
+
+ private record ResolvedType(String qualifiedName, String url, boolean isExternal) {}
+
+ /**
+ * Looks up a type's package in {@link #externalPackages} and builds the
+ * Javadoc URL for that type. Returns {@code null} when the package is not
+ * in the external index.
+ *
+ * The {@code -link} option stores entries in the form
+ * {@code "baseUrl/index.html?java/util/"} for package {@code java.util}.
+ * We append the simple class name ({@code List.html}) to produce the final
+ * URL: {@code "baseUrl/index.html?java/util/List.html"}.
+ */
+ @Nullable
+ private String resolveExternalTypeUrl(String qualifiedName) {
+ if (qualifiedName == null || qualifiedName.isBlank()) {
+ return null;
+ }
+ int lastDot = qualifiedName.lastIndexOf('.');
+ if (lastDot <= 0) {
+ return null;
+ }
+ String packageName = qualifiedName.substring(0, lastDot);
+ String simpleName = qualifiedName.substring(lastDot + 1);
+ String baseUrl = externalPackages.get(packageName);
+ if (baseUrl == null) {
+ return null;
+ }
+ // baseUrl is stored as e.g. "https://…/api/index.html?java/util/"
+ // Appending "List.html" gives "https://…/api/index.html?java/util/List.html".
+ // Strip any trailing slash first so we always end up with exactly one separator.
+ String trimmed = baseUrl.endsWith("/") ? baseUrl.substring(0, baseUrl.length() - 1) : baseUrl;
+ return trimmed + "/" + simpleName + ".html";
+ }
+
+ // -------------------------------------------------------------------------
+ // Link resolution — called from the DocBodyRenderer linkResolver lambda.
+ // -------------------------------------------------------------------------
+
+ /**
+ * Resolves a {@link DocBodyNode.Link} to a Markdown link string.
+ * Falls back to a plain label when the target cannot be found.
+ */
+ private String resolveLink(DocBodyNode.Link link, ClassDoc context) {
+ String sig = link.signature();
+
+ // Check for simple Java type aliases first (String, Boolean, boxed numbers).
+ String mapped = DocBodyRenderer.mapSimpleLinkSignature(sig);
+ if (mapped != null) {
+ return mapped;
+ }
+
+ LinkSignature parsed = parseSignature(sig);
+ if (parsed == null) {
+ String label = link.label() != null ? link.label() : linkLabel(sig);
+ // If the bare sig looks like a signature, wrap it in a code span.
+ if (DocBodyRenderer.looksLikeSignature(sig)) {
+ return MarkdownBuilder.codeSpan(DocBodyRenderer.convertSignature(sig));
+ }
+ return label;
+ }
+ ClassDoc targetClass = resolveClass(parsed.className(), context);
+ if (targetClass == null) {
+ String label = link.label() != null ? link.label() : linkLabel(sig);
+ return label;
+ }
+ String anchor = resolveMemberAnchor(targetClass, parsed);
+ String url = buildLinkUrl(targetClass, anchor, context);
+ String label = link.label() != null ? link.label() : linkLabel(sig);
+ return "[" + label + "](" + url + ")";
+ }
+
+ /**
+ * Resolves a {@link DocBodyNode.Link} to an HTML {@code } element string.
+ * Used when rendering inside raw HTML blocks (overload-body, param lists, etc.)
+ * where Markdown link syntax is not processed by VitePress.
+ */
+ private String resolveLinkAsHtml(DocBodyNode.Link link, ClassDoc context) {
+ String sig = link.signature();
+
+ String mapped = DocBodyRenderer.mapSimpleLinkSignature(sig);
+ if (mapped != null) {
+ return "" + escapeHtml(mapped) + "";
+ }
+
+ LinkSignature parsed = parseSignature(sig);
+ String label = link.label() != null ? link.label() : linkLabel(sig);
+ if (parsed == null) {
+ if (DocBodyRenderer.looksLikeSignature(sig)) {
+ return "" + escapeHtml(DocBodyRenderer.convertSignature(sig)) + "";
+ }
+ return escapeHtml(label);
+ }
+ ClassDoc targetClass = resolveClass(parsed.className(), context);
+ if (targetClass == null) {
+ return escapeHtml(label);
+ }
+ String anchor = resolveMemberAnchor(targetClass, parsed);
+ String url = buildLinkUrl(targetClass, anchor, context);
+ return "" + escapeHtml(label) + "";
+ }
+
+ private String buildLinkUrl(ClassDoc targetClass, String anchor, ClassDoc context) {
+ // Anchors on the page are qualified: "qualifiedName_anchorId" (e.g. "com.example.Foo_bar-String-").
+ String qualifiedAnchor = anchor != null ? targetClass.qualifiedName() + "_" + anchor : null;
+ if (context != null && targetClass.qualifiedName().equals(context.qualifiedName())) {
+ return qualifiedAnchor == null ? "#" : "#" + qualifiedAnchor;
+ }
+
+ String url;
+ if (context == null) {
+ url = "/" + version + "/" + classPath(targetClass);
+ } else {
+ Path from = Path.of(classPath(context));
+ Path to = Path.of(classPath(targetClass));
+ Path fromParent = from.getParent();
+ url = (fromParent == null ? to : fromParent.relativize(to)).toString().replace(File.separatorChar, '/');
+ if (url.isBlank()) {
+ url = "#";
+ }
+ }
+ if (qualifiedAnchor != null) {
+ url = url + "#" + qualifiedAnchor;
+ }
+ return url;
+ }
+
+ @Nullable
+ private ClassDoc resolveClass(String name, ClassDoc context) {
+ if (name == null || name.isBlank()) {
+ return context;
+ }
+ String cleaned = name.startsWith("Packages.") ? name.substring("Packages.".length()) : name;
+ int genericIndex = cleaned.indexOf('<');
+ if (genericIndex != -1) {
+ cleaned = cleaned.substring(0, genericIndex).trim();
+ }
+ ClassDoc direct = classByQualifiedName.get(cleaned);
+ if (direct != null) {
+ return direct;
+ }
+ List matches = new ArrayList<>();
+ List nameMatches = classByName.get(cleaned);
+ if (nameMatches != null) {
+ matches.addAll(nameMatches);
+ }
+ List aliasMatches = classByAlias.get(cleaned);
+ if (aliasMatches != null) {
+ matches.addAll(aliasMatches);
+ }
+ if (matches.isEmpty()) {
+ return null;
+ }
+ if (matches.size() == 1 || context == null) {
+ return matches.getFirst();
+ }
+ for (ClassDoc match : matches) {
+ if (match.packageName().equals(context.packageName())) {
+ return match;
+ }
+ }
+ return matches.getFirst();
+ }
+
+ @Nullable
+ private LinkSignature parseSignature(String signature) {
+ if (signature == null) {
+ return null;
+ }
+ String trimmed = signature.trim();
+ if (trimmed.isEmpty()) {
+ return null;
+ }
+ String classPart = null;
+ String memberPart = null;
+ int hashIndex = trimmed.indexOf('#');
+ if (hashIndex == 0) {
+ memberPart = trimmed.substring(1);
+ } else if (hashIndex > 0) {
+ classPart = trimmed.substring(0, hashIndex);
+ memberPart = trimmed.substring(hashIndex + 1);
+ } else {
+ classPart = trimmed;
+ }
+ String memberName = null;
+ List params = null;
+ if (memberPart != null && !memberPart.isBlank()) {
+ int parenIndex = memberPart.indexOf('(');
+ if (parenIndex != -1 && memberPart.endsWith(")")) {
+ memberName = memberPart.substring(0, parenIndex);
+ String paramBody = memberPart.substring(parenIndex + 1, memberPart.length() - 1);
+ params = splitParams(paramBody);
+ } else {
+ memberName = memberPart;
+ }
+ }
+ return new LinkSignature(classPart, memberName, params);
+ }
+
+ private List splitParams(String paramBody) {
+ List params = new ArrayList<>();
+ if (paramBody == null || paramBody.isBlank()) {
+ return params;
+ }
+ int depth = 0;
+ StringBuilder current = new StringBuilder();
+ for (int i = 0; i < paramBody.length(); i++) {
+ char ch = paramBody.charAt(i);
+ if (ch == '<') {
+ depth++;
+ } else if (ch == '>' && depth > 0) {
+ depth--;
+ }
+ if (ch == ',' && depth == 0) {
+ params.add(current.toString().trim());
+ current.setLength(0);
+ } else {
+ current.append(ch);
+ }
+ }
+ if (!current.isEmpty()) {
+ params.add(current.toString().trim());
+ }
+ return params;
+ }
+
+ @Nullable
+ private String resolveMemberAnchor(ClassDoc clz, LinkSignature signature) {
+ if (signature.memberName() == null) {
+ return null;
+ }
+ List members = new ArrayList<>();
+ for (MemberDoc member : clz.members()) {
+ if (member.name().equals(signature.memberName())) {
+ members.add(member);
+ }
+ }
+ if (members.isEmpty() && signature.memberName().equals(clz.name())) {
+ for (MemberDoc member : clz.members()) {
+ if (member.kind() == MemberKind.CONSTRUCTOR) {
+ members.add(member);
+ }
+ }
+ }
+ if (members.isEmpty()) {
+ return null;
+ }
+ List params = signature.paramTypes();
+ if (params == null) {
+ return members.size() == 1 ? members.getFirst().anchorId() : null;
+ }
+ for (MemberDoc member : members) {
+ if (paramsMatch(member, params)) {
+ return member.anchorId();
+ }
+ }
+ return null;
+ }
+
+ private boolean paramsMatch(MemberDoc member, List params) {
+ if (member.params().size() != params.size()) {
+ return false;
+ }
+ for (int i = 0; i < params.size(); i++) {
+ String expected = normalizeParamType(params.get(i));
+ ParamDoc param = member.params().get(i);
+ String actual = normalizeParamType(memberParamTypeName(param));
+ if (!expected.equals(actual)) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ private String memberParamTypeName(ParamDoc param) {
+ return memberParamTypeName(param.type(), param.varArgs());
+ }
+
+ private String memberParamTypeName(TypeRef type, boolean varArgs) {
+ String base = type.kind() == TypeKind.ARRAY
+ ? memberParamTypeName(type.typeArgs().getFirst(), false) + "[]"
+ : type.name();
+ if (varArgs && type.kind() != TypeKind.ARRAY) {
+ base = base + "[]";
+ }
+ return base;
+ }
+
+ private String normalizeParamType(String type) {
+ if (type == null) {
+ return "";
+ }
+ String normalized = type.trim();
+ if (normalized.isEmpty()) {
+ return "";
+ }
+ if (normalized.startsWith("?")) {
+ return "?";
+ }
+ int arrayDepth = 0;
+ while (normalized.endsWith("[]")) {
+ normalized = normalized.substring(0, normalized.length() - 2).trim();
+ arrayDepth++;
+ }
+ if (normalized.endsWith("...")) {
+ normalized = normalized.substring(0, normalized.length() - 3).trim();
+ arrayDepth++;
+ }
+ int genericIndex = normalized.indexOf('<');
+ if (genericIndex != -1) {
+ normalized = normalized.substring(0, genericIndex).trim();
+ }
+ normalized = stripPackageName(normalized);
+ return normalized + "[]".repeat(Math.max(0, arrayDepth));
+ }
+
+ private String stripPackageName(String name) {
+ if (name == null || name.isBlank()) {
+ return "";
+ }
+ if (!name.contains(".")) {
+ return name;
+ }
+ String[] parts = name.split("\\.");
+ int firstTypeIndex = -1;
+ for (int i = 0; i < parts.length; i++) {
+ String part = parts[i];
+ if (!part.isEmpty() && Character.isUpperCase(part.charAt(0))) {
+ firstTypeIndex = i;
+ break;
+ }
+ }
+ if (firstTypeIndex == -1) {
+ return parts[parts.length - 1];
+ }
+ StringBuilder builder = new StringBuilder();
+ for (int i = firstTypeIndex; i < parts.length; i++) {
+ if (!builder.isEmpty()) {
+ builder.append(".");
+ }
+ builder.append(parts[i]);
+ }
+ return builder.toString();
+ }
+
+ private String linkLabel(String signature) {
+ if (signature == null) {
+ return "";
+ }
+ String cleaned = signature.trim();
+ if (cleaned.startsWith("Packages.")) {
+ cleaned = cleaned.substring("Packages.".length());
+ }
+ int hashIndex = cleaned.indexOf('#');
+ if (hashIndex == 0) {
+ return cleaned.substring(1);
+ }
+ if (hashIndex > 0) {
+ String classPart = cleaned.substring(0, hashIndex);
+ String memberPart = cleaned.substring(hashIndex + 1);
+ String classLabel = stripPackageName(classPart);
+ if (classLabel.isBlank()) {
+ return memberPart;
+ }
+ return classLabel + "." + memberPart;
+ }
+ return stripPackageName(cleaned);
+ }
+
+ private String simpleName(String name) {
+ int idx = name.lastIndexOf('.');
+ return idx == -1 ? name : name.substring(idx + 1);
+ }
+
+ private record LinkSignature(String className, String memberName, List paramTypes) {}
+
+ /**
+ *
+ */
+ private class Syntax {
+ /**
+ * Wraps the given text in an HTML element with optional attributes, for embedding inside raw
+ * HTML blocks. Use when the content is already fully rendered to HTML and just needs a
+ * wrapper element.
+ * @param inner the already-rendered HTML content to wrap
+ * @param elem the HTML element name, e.g. "div", "p", "li"
+ * @param attribs optional raw attributes to include in the opening tag, e.g. "class=\"foo\" id=\"bar\""
+ * @return the combined HTML string with the wrapper element and attributes around the inner content
+ */
+ private static String wrapHtmlWithElemAndAttribs(String inner, String elem, String attribs) {
+ StringBuilder sb = new StringBuilder();
+ if (attribs != null && !attribs.isBlank()) {
+ attribs = " " + attribs.trim();
+ } else {
+ attribs = "";
+ }
+ sb.append("<").append(elem).append(attribs).append(">");
+ sb.append(inner);
+ sb.append("");
+ return sb.toString();
+ }
+
+ /**
+ * Wraps the given text in an HTML element with optional attributes, for embedding inside raw
+ * HTML blocks. Use when the content is already fully rendered to HTML and just needs a
+ * wrapper element.
+ * @see #wrapHtmlWithElemAndAttribs(String, String, String) for the variant with attributes.
+ * @param inner the already-rendered HTML content to wrap
+ * @param elem the HTML element name, e.g. "div", "p", "li"
+ * @return the combined HTML string with the wrapper element around the inner content
+ */
+ private static String wrapHtmlWithElem(String inner, String elem) {
+ return wrapHtmlWithElemAndAttribs(inner, elem, null);
+ }
+
+ /**
+ * Wraps the given content in a with class "syntax-token-{type}", for syntax highlighting.
+ * @param type the token type, e.g. "keyword", "class-name", "punctuation"
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String tok(String type, String content) {
+ return wrapHtmlWithElemAndAttribs(content, "span", "class=\"syntax-token-" + type + "\"");
+ }
+
+ /**
+ * Returns the given content wrapped in a "keyword" token span.
+ * Ex. "new", "extends", "implements"
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String keyword(String content) {
+ return tok("keyword", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "method" token span.
+ * Ex. method names, constructor names, field names
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String method(String content) {
+ return tok("method", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "class" token span.
+ * Ex. class names, interface names, enum names, annotation names
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String clazz(String content) {
+ return tok("class", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "type" token span.
+ * Ex. type parameters, type variable names
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String type(String content) {
+ return tok("type", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "linked-type" token span.
+ * Ex. type parameters, type variable
+ * @param content the already-rendered wrapped HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String linkedType(String content) {
+ return tok("linked-type", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "parameter" token span.
+ * Ex. parameter names in method signatures
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String parameter(String content) {
+ return tok("parameter", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "punctuation" token span.
+ * Ex. "(", ")", "{", "}", "[", "]", ";", ",", ".", "::", ":", "<", ">"
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String punctuation(String content) {
+ return tok("punctuation", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "wildcard" token span.
+ * Ex. "?"
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String wildcard(String content) {
+ return tok("wildcard", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "primative" token span.
+ * Ex. "?"
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String primative(String content) {
+ return tok("primative", content);
+ }
+
+ /**
+ * Returns the given content wrapped in a "typevar" token span.
+ * Ex. type variable names like "T" and "E"
+ * @param content the already-rendered HTML content to wrap
+ * @return the combined HTML string with the wrapper and token class around the inner content
+ */
+ public static String typeVar(String content) {
+ return tok("typevar", content);
+ }
+
+ /**
+ * Returns the given raw HTML string wrapped in a element, for embedding inside
+ * Shiki-highlighted code blocks where the content is already fully rendered to HTML
+ * and just needs a wrapper element.
+ * @param html the raw HTML string to wrap
+ * @return the combined HTML string with the wrapper around the inner content
+ */
+ public static String raw(String html) {
+ return html;
+ }
+ }
+}
diff --git a/buildSrc/src/main/java/com/jsmacrosce/doclet/core/render/PythonWriter.java b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/render/PythonWriter.java
new file mode 100644
index 000000000..1fe1f9292
--- /dev/null
+++ b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/render/PythonWriter.java
@@ -0,0 +1,609 @@
+package com.jsmacrosce.doclet.core.render;
+
+import com.jsmacrosce.FileHandler;
+import com.jsmacrosce.doclet.DocletIgnore;
+import com.jsmacrosce.doclet.core.ClassGroup;
+import com.jsmacrosce.doclet.core.model.ClassDoc;
+import com.jsmacrosce.doclet.core.model.DocBodyNode;
+import com.jsmacrosce.doclet.core.model.DocComment;
+import com.jsmacrosce.doclet.core.model.DocTagKind;
+import com.jsmacrosce.doclet.core.model.DocletModel;
+import com.jsmacrosce.doclet.core.model.MemberDoc;
+import com.jsmacrosce.doclet.core.model.MemberKind;
+import com.jsmacrosce.doclet.core.model.PackageDoc;
+import com.jsmacrosce.doclet.core.model.ParamDoc;
+import com.jsmacrosce.doclet.core.model.TypeRef;
+import com.jsmacrosce.doclet.core.util.DocBodyRenderer;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.TreeSet;
+
+@DocletIgnore
+public class PythonWriter {
+ private static final Set PYTHON_KEYWORDS = new LinkedHashSet<>(Arrays.asList(
+ "False", "await", "else", "import", "pass", "None", "break", "except",
+ "in", "raise", "True", "class", "finally", "is", "return", "and",
+ "continue", "for", "lambda", "try", "as", "def", "from", "nonlocal",
+ "while", "assert", "del", "global", "not", "with", "async", "elif",
+ "if", "or", "yield"
+ ));
+
+ public PythonWriter() {}
+
+ public void write(DocletModel model, File outDir, String version) throws IOException {
+ Map classNameByQualified = new LinkedHashMap<>();
+ for (PackageDoc pkg : model.packages()) {
+ for (ClassDoc clz : pkg.classes()) {
+ classNameByQualified.put(clz.qualifiedName(), pythonClassName(clz));
+ }
+ }
+
+ for (PackageDoc pkg : model.packages()) {
+ for (ClassDoc clz : pkg.classes()) {
+ String fileName = pythonClassName(clz);
+ File out = new File(outDir, fileName + ".py");
+ new FileHandler(out).write(renderClass(clz, classNameByQualified));
+ }
+ }
+
+ Map> grouped = groupClasses(model);
+ List groupOrder = List.of("libraries", "events", "helpers", "mixins", "rest");
+ List groupModules = new ArrayList<>();
+ for (String group : groupOrder) {
+ List classes = grouped.get(group);
+ if (classes == null || classes.isEmpty()) {
+ continue;
+ }
+ groupModules.add(group);
+ new FileHandler(new File(outDir, group + ".py"))
+ .write(renderGroupModule(group, classes));
+ }
+
+ StringBuilder init = new StringBuilder();
+ for (String module : groupModules) {
+ init.append("from .").append(module).append(" import *\n");
+ }
+ new FileHandler(new File(outDir, "__init__.py")).write(init.toString());
+
+ if (version != null) {
+ new FileHandler(new File(outDir, "setup.py"))
+ .write(renderSetupPy(version));
+ }
+ }
+
+ private String pythonClassName(ClassDoc clz) {
+ return clz.name().replace('.', '_');
+ }
+
+ private String renderClass(ClassDoc clz, Map classNameByQualified) {
+ PythonTypeContext ctx = new PythonTypeContext(classNameByQualified, pythonClassName(clz));
+ StringBuilder body = new StringBuilder();
+
+ body.append(renderClassLine(clz, ctx));
+ appendDocstring(body, 1, clz.docComment(), List.of(), false);
+
+ for (MemberDoc member : clz.members()) {
+ if (member.kind() == MemberKind.FIELD) {
+ body.append(" ")
+ .append(getVarName(member.name()))
+ .append(": ")
+ .append(ctx.formatType(member.returnType(), false))
+ .append("\n");
+ }
+ }
+
+ for (MemberDoc member : clz.members()) {
+ if (member.kind() == MemberKind.CONSTRUCTOR) {
+ body.append(renderConstructor(member, ctx));
+ } else if (member.kind() == MemberKind.METHOD) {
+ body.append(renderMethod(member, ctx));
+ }
+ }
+
+ body.append(" pass\n\n");
+
+ StringBuilder builder = new StringBuilder();
+ builder.append(ctx.renderImports());
+ builder.append(body);
+ return builder.toString();
+ }
+
+ private String renderConstructor(MemberDoc member, PythonTypeContext ctx) {
+ StringBuilder builder = new StringBuilder();
+ ctx.setOverloadUsed(true);
+ builder.append(" @overload\n");
+ builder.append(" def __init__(self");
+ appendParams(builder, member.params(), ctx);
+ builder.append(") -> None:\n");
+ appendDocstring(builder, 2, member.docComment(), member.params(), false);
+ builder.append(" pass\n\n");
+ return builder.toString();
+ }
+
+ private String renderMethod(MemberDoc member, PythonTypeContext ctx) {
+ StringBuilder builder = new StringBuilder();
+ ctx.setOverloadUsed(true);
+ builder.append(" @overload\n");
+ builder.append(" def ").append(getVarName(member.name())).append("(self");
+ appendParams(builder, member.params(), ctx);
+ builder.append(") -> ").append(ctx.formatType(member.returnType(), false)).append(":\n");
+ appendDocstring(builder, 2, member.docComment(), member.params(), true);
+ builder.append(" pass\n\n");
+ return builder.toString();
+ }
+
+ private void appendParams(StringBuilder builder, List params, PythonTypeContext ctx) {
+ for (ParamDoc param : params) {
+ builder.append(", ").append(getVarName(param.name())).append(": ")
+ .append(ctx.formatType(param.type(), false));
+ }
+ }
+
+ private void appendDocstring(
+ StringBuilder builder,
+ int indent,
+ DocComment comment,
+ List params,
+ boolean includeReturn
+ ) {
+ String desc = formatDescription(comment);
+ String since = getTagText(comment, DocTagKind.SINCE);
+ Map tagDocs = new LinkedHashMap<>();
+ if (comment != null) {
+ comment.tags().stream()
+ .filter(tag -> tag.kind() == DocTagKind.PARAM && tag.name() != null)
+ .forEach(tag -> tagDocs.put(tag.name(), DocBodyRenderer.toPlainText(tag.body(), link -> link.label() != null ? link.label() : link.signature())));
+ }
+ Map paramDocs = new LinkedHashMap<>();
+ if (params != null) {
+ for (ParamDoc param : params) {
+ if (tagDocs.containsKey(param.name())) {
+ paramDocs.put(param.name(), tagDocs.get(param.name()));
+ }
+ }
+ }
+ String ret = includeReturn ? getTagText(comment, DocTagKind.RETURN) : "";
+
+ if (desc.isEmpty() && since.isEmpty() && paramDocs.isEmpty() && ret.isEmpty()) {
+ return;
+ }
+
+ String pad = " ".repeat(indent);
+ builder.append(pad).append("\"\"\"");
+ if (!desc.isEmpty()) {
+ builder.append(escape(desc));
+ }
+ if (!since.isEmpty()) {
+ if (!desc.isEmpty()) {
+ builder.append("\n");
+ }
+ builder.append("Since: ").append(escape(since));
+ }
+ if (!paramDocs.isEmpty()) {
+ builder.append("\n\n").append(pad).append("Args:\n");
+ for (Map.Entry entry : paramDocs.entrySet()) {
+ builder.append(pad).append(" ")
+ .append(getVarName(entry.getKey()))
+ .append(": ")
+ .append(escape(entry.getValue()))
+ .append("\n");
+ }
+ builder.setLength(builder.length() - 1);
+ }
+ if (!ret.isEmpty()) {
+ builder.append("\n\n").append(pad).append("Returns:\n");
+ builder.append(pad).append(" ").append(escape(ret));
+ }
+ builder.append("\n").append(pad).append("\"\"\"\n");
+ }
+
+ private String renderClassLine(ClassDoc clz, PythonTypeContext ctx) {
+ StringBuilder builder = new StringBuilder("\nclass ");
+ builder.append(pythonClassName(clz));
+
+ List bases = new ArrayList<>();
+ for (TypeRef iface : clz.implementsTypes()) {
+ String name = ctx.formatType(iface, true);
+ if (!name.isBlank()) {
+ bases.add(name);
+ }
+ }
+ if (!clz.typeParams().isEmpty()) {
+ ctx.setGenericUsed(true);
+ StringBuilder typeParams = new StringBuilder("Generic[");
+ for (TypeRef param : clz.typeParams()) {
+ String name = ctx.formatType(param, true);
+ typeParams.append(name).append(", ");
+ }
+ typeParams.setLength(typeParams.length() - 2);
+ typeParams.append("]");
+ bases.add(typeParams.toString());
+ }
+ for (TypeRef extend : clz.extendsTypes()) {
+ String name = ctx.formatType(extend, true);
+ if (!name.isBlank()) {
+ bases.add(name);
+ }
+ }
+
+ if (!bases.isEmpty()) {
+ builder.append("(");
+ for (String base : bases) {
+ builder.append(base).append(", ");
+ }
+ builder.setLength(builder.length() - 2);
+ builder.append(")");
+ }
+ builder.append(":\n");
+ return builder.toString();
+ }
+
+ private String renderGroupModule(String group, List classes) {
+ StringBuilder builder = new StringBuilder();
+ builder.append("from typing import TypeVar\n\n");
+ builder.append("from .EventContainer import EventContainer\n");
+ builder.append("from .BaseEvent import BaseEvent\n");
+
+ for (ClassDoc clz : classes) {
+ String name = pythonClassName(clz);
+ builder.append("from .").append(name).append(" import ").append(name).append("\n");
+ }
+
+ builder.append("\nFile = TypeVar(\"java.io.File\")\n\n");
+ if ("libraries".equals(group)) {
+ builder.append("\n\n");
+ for (ClassDoc clz : classes) {
+ String name = pythonClassName(clz);
+ String alias = clz.alias() == null || clz.alias().isEmpty() ? name : clz.alias();
+ builder.append(alias).append(" = ").append(name).append("()\n");
+ }
+ builder.append("context = EventContainer()\n");
+ builder.append("file = File()\n");
+ builder.append("event = BaseEvent()\n");
+ }
+
+ return builder.toString();
+ }
+
+ private Map> groupClasses(DocletModel model) {
+ Map> grouped = new LinkedHashMap<>();
+ for (PackageDoc pkg : model.packages()) {
+ for (ClassDoc clz : pkg.classes()) {
+ String name = clz.name();
+ String key;
+ if (clz.group() == ClassGroup.Library) {
+ key = "libraries";
+ } else if (clz.group() == ClassGroup.Event) {
+ key = "events";
+ } else if (name.contains("Helper")) {
+ key = "helpers";
+ } else if (name.contains("Mixin")) {
+ key = "mixins";
+ } else {
+ key = "rest";
+ }
+ grouped.computeIfAbsent(key, value -> new ArrayList<>()).add(clz);
+ }
+ }
+ return grouped;
+ }
+
+ private String renderSetupPy(String version) {
+ String cleaned = version;
+ if (cleaned.contains("-")) {
+ cleaned = cleaned.split("-", 2)[0];
+ }
+ StringBuilder sb = new StringBuilder();
+ sb.append("""
+ from setuptools import setup, find_packages
+ from os import path
+ import os
+ import time
+
+ this_directory = path.abspath(path.dirname(__file__))
+ with open(path.join(this_directory, 'README.md'), encoding='utf-8') as f:
+ long_description = f.read()
+
+
+ VERSION = '""");
+ sb.append(cleaned);
+ sb.append("""
+ '
+ if "-" in VERSION: VERSION = VERSION.split("-")[0]
+ VERSION += "." + str(time.time()).split(".")[0][3:]
+ DESCRIPTION = 'A package to let your IDE know what JsMacros can do'
+
+ def package_files(directory):
+ paths = []
+ for (path, directories, filenames) in os.walk(directory):
+ for filename in filenames:
+ paths.append(os.path.join('..', path, filename))
+ return paths
+
+ extra_files = package_files('JsMacrosAC')
+
+ # Setting up
+ setup(
+ name="JsMacrosAC",
+ version=VERSION,
+ author="Hasenzahn1",
+ author_email="",
+ description=DESCRIPTION,
+ long_description_content_type="text/markdown",
+ long_description=long_description,
+ packages=["JsMacrosAC"],
+ package_data = {"": extra_files},
+ install_requires=[],
+ keywords=['python', 'JsMacros', 'Autocomplete', 'Doc'],
+ classifiers=[
+ "Intended Audience :: Developers",
+ "Programming Language :: Python :: 3",
+ "Operating System :: Unix",
+ "Operating System :: MacOS :: MacOS X",
+ "Operating System :: Microsoft :: Windows",
+ ]
+ )""");
+ return sb.toString();
+ }
+
+ private String formatDescription(DocComment comment) {
+ if (comment == null) {
+ return "";
+ }
+ List nodes = comment.body().isEmpty() ? comment.summary() : comment.body();
+ return DocBodyRenderer.toPlainText(nodes, link -> link.label() != null ? link.label() : link.signature());
+ }
+
+ private String getTagText(DocComment comment, DocTagKind kind) {
+ if (comment == null) {
+ return "";
+ }
+ return comment.tags().stream()
+ .filter(tag -> tag.kind() == kind)
+ .map(tag -> DocBodyRenderer.toPlainText(tag.body(), link -> link.label() != null ? link.label() : link.signature()))
+ .findFirst()
+ .orElse("");
+ }
+
+ private String escape(String text) {
+ return text.replace("\"\"\"", "''");
+ }
+
+ private String getVarName(String name) {
+ return PYTHON_KEYWORDS.contains(name) ? name + "_" : name;
+ }
+
+ private static class PythonTypeContext {
+ private static final Map TYPE_ALIASES = Map.ofEntries(
+ Map.entry("java.lang.Object", "object"),
+ Map.entry("java.lang.String", "str"),
+ Map.entry("java.lang.Integer", "int"),
+ Map.entry("java.lang.Boolean", "bool"),
+ Map.entry("java.lang.Double", "float"),
+ Map.entry("java.lang.Float", "float"),
+ Map.entry("java.lang.Long", "float"),
+ Map.entry("java.lang.Short", "float"),
+ Map.entry("java.lang.Byte", "float"),
+ Map.entry("java.lang.Character", "str"),
+ Map.entry("java.lang.annotation.Annotation", ""),
+ Map.entry("java.lang.Enum", "")
+ );
+ private static final Set UNWANTED_CLASS = Set.of(
+ "java.lang.Object",
+ "java.lang.annotation.Annotation",
+ "java.lang.Enum",
+ "java.util.Collection"
+ );
+ private static final Map WITH_ARG = Map.of(
+ "java.util.Set", "Set",
+ "java.util.List", "List",
+ "java.util.Map", "Mapping",
+ "java.util.Collection", "List"
+ );
+ private static final List EXTERNAL_PREFIXES = List.of(
+ "net.", "com.", "io.", "org.", "java.", "javax.", "jdk."
+ );
+
+ private final Map classNameByQualified;
+ private final String currentClassName;
+ private final Set internalImports = new TreeSet<>();
+ private final Map externalTypeVars = new TreeMap<>();
+ private final Set typeVars = new TreeSet<>();
+ private boolean overloadUsed;
+ private boolean importList;
+ private boolean importTypeVar;
+ private boolean importAny;
+ private boolean importMapping;
+ private boolean importSet;
+ private boolean importGeneric;
+
+ private PythonTypeContext(Map classNameByQualified, String currentClassName) {
+ this.classNameByQualified = classNameByQualified;
+ this.currentClassName = currentClassName;
+ }
+
+ String formatType(TypeRef type, boolean classContext) {
+ if (type == null) {
+ importAny = true;
+ return "Any";
+ }
+ return switch (type.kind()) {
+ case PRIMITIVE -> switch (type.name()) {
+ case "boolean" -> "bool";
+ case "int" -> "int";
+ case "char" -> "str";
+ case "byte", "short", "long", "float", "double" -> "float";
+ default -> "int";
+ };
+ case VOID -> "None";
+ case ARRAY -> {
+ importList = true;
+ String component = formatType(type.typeArgs().get(0), false);
+ yield "List[" + component + "]";
+ }
+ case TYPEVAR -> {
+ importTypeVar = true;
+ typeVars.add(type.name());
+ yield type.name();
+ }
+ case WILDCARD -> {
+ importAny = true;
+ yield "Any";
+ }
+ case DECLARED -> formatDeclared(type, classContext);
+ default -> "Any";
+ };
+ }
+
+ private String formatDeclared(TypeRef type, boolean classContext) {
+ String qualified = type.qualifiedName();
+ if (classContext && UNWANTED_CLASS.contains(qualified)) {
+ return "";
+ }
+ if (TYPE_ALIASES.containsKey(qualified)) {
+ return TYPE_ALIASES.get(qualified);
+ }
+ if (WITH_ARG.containsKey(qualified)) {
+ String base = WITH_ARG.get(qualified);
+ if ("List".equals(base)) {
+ importList = true;
+ } else if ("Mapping".equals(base)) {
+ importMapping = true;
+ } else if ("Set".equals(base)) {
+ importSet = true;
+ }
+ if (type.typeArgs().isEmpty()) {
+ importAny = true;
+ return base + "[Any]";
+ }
+ StringBuilder builder = new StringBuilder(base);
+ builder.append("[");
+ for (TypeRef arg : type.typeArgs()) {
+ builder.append(formatType(arg, false)).append(", ");
+ }
+ builder.setLength(builder.length() - 2);
+ builder.append("]");
+ return builder.toString();
+ }
+
+ String className = type.name().replace('.', '_');
+ if (className.equals(currentClassName)) {
+ return "\"" + className + "\"";
+ }
+ if (classNameByQualified.containsKey(qualified)) {
+ String importName = classNameByQualified.get(qualified);
+ if (!importName.equals(currentClassName)) {
+ internalImports.add(importName);
+ }
+ if (!type.typeArgs().isEmpty()) {
+ StringBuilder builder = new StringBuilder(importName);
+ builder.append("[");
+ for (TypeRef arg : type.typeArgs()) {
+ builder.append(formatType(arg, false)).append(", ");
+ }
+ builder.setLength(builder.length() - 2);
+ builder.append("]");
+ return builder.toString();
+ }
+ return importName;
+ }
+
+ if (isExternalType(qualified)) {
+ importTypeVar = true;
+ String typeVarName = sanitizeTypeVarName(qualified);
+ externalTypeVars.put(className, typeVarName);
+ return className;
+ }
+
+ if (!type.typeArgs().isEmpty()) {
+ StringBuilder builder = new StringBuilder(className);
+ builder.append("[");
+ for (TypeRef arg : type.typeArgs()) {
+ builder.append(formatType(arg, false)).append(", ");
+ }
+ builder.setLength(builder.length() - 2);
+ builder.append("]");
+ return builder.toString();
+ }
+ return className;
+ }
+
+ private boolean isExternalType(String qualifiedName) {
+ for (String prefix : EXTERNAL_PREFIXES) {
+ if (qualifiedName.startsWith(prefix)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ private String sanitizeTypeVarName(String qualifiedName) {
+ return qualifiedName.replace("<", "_")
+ .replace(">", "_")
+ .replace("?", "")
+ .replace(".", "_");
+ }
+
+ String renderImports() {
+ StringBuilder builder = new StringBuilder();
+ if (overloadUsed) {
+ builder.append("from typing import overload\n");
+ }
+ if (importList) {
+ builder.append("from typing import List\n");
+ }
+ if (importTypeVar) {
+ builder.append("from typing import TypeVar\n");
+ }
+ if (importAny) {
+ builder.append("from typing import Any\n");
+ }
+ if (importMapping) {
+ builder.append("from typing import Mapping\n");
+ }
+ if (importSet) {
+ builder.append("from typing import Set\n");
+ }
+ if (importGeneric) {
+ builder.append("from typing import Generic\n");
+ }
+ for (String imp : internalImports) {
+ builder.append("from .").append(imp).append(" import ").append(imp).append("\n");
+ }
+ builder.append("\n");
+
+ for (String typeVar : typeVars) {
+ builder.append(typeVar).append(" = TypeVar(\"").append(typeVar).append("\")\n");
+ }
+ for (Map.Entry entry : externalTypeVars.entrySet()) {
+ String className = entry.getKey();
+ String typeVarName = entry.getValue();
+ if ("T".equals(typeVarName) || "U".equals(typeVarName) || "R".equals(typeVarName)) {
+ builder.append(typeVarName).append(" = TypeVar(\"").append(typeVarName).append("\")\n");
+ } else {
+ builder.append(typeVarName).append(" = TypeVar(\"").append(typeVarName).append("\")\n");
+ builder.append(className).append(" = ").append(typeVarName).append("\n\n");
+ }
+ }
+
+ return builder.toString();
+ }
+
+ void setOverloadUsed(boolean overloadUsed) {
+ this.overloadUsed = overloadUsed;
+ }
+
+ void setGenericUsed(boolean genericUsed) {
+ this.importGeneric = genericUsed;
+ }
+ }
+}
diff --git a/buildSrc/src/main/java/com/jsmacrosce/doclet/core/render/TsRenderer.java b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/render/TsRenderer.java
new file mode 100644
index 000000000..48cdb6c22
--- /dev/null
+++ b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/render/TsRenderer.java
@@ -0,0 +1,824 @@
+package com.jsmacrosce.doclet.core.render;
+
+import com.jsmacrosce.doclet.DocletIgnore;
+import com.jsmacrosce.doclet.core.*;
+import com.jsmacrosce.doclet.core.model.ClassDoc;
+import com.jsmacrosce.doclet.core.model.ClassKind;
+import com.jsmacrosce.doclet.core.model.DeclaredTypeDoc;
+import com.jsmacrosce.doclet.core.model.DocBodyNode;
+import com.jsmacrosce.doclet.core.model.DocComment;
+import com.jsmacrosce.doclet.core.model.DocTag;
+import com.jsmacrosce.doclet.core.model.DocTagKind;
+import com.jsmacrosce.doclet.core.model.DocletModel;
+import com.jsmacrosce.doclet.core.model.MemberDoc;
+import com.jsmacrosce.doclet.core.model.MemberKind;
+import com.jsmacrosce.doclet.core.model.PackageDoc;
+import com.jsmacrosce.doclet.core.model.ParamDoc;
+import com.jsmacrosce.doclet.core.model.TypeKind;
+import com.jsmacrosce.doclet.core.model.TypeRef;
+import com.jsmacrosce.doclet.core.util.DocBodyRenderer;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.TreeSet;
+
+
+@DocletIgnore
+public class TsRenderer implements Renderer {
+ private static final Set TS_RESERVED_WORDS = Set.of(
+ "break", "case", "catch", "class", "const", "continue", "debugger", "default",
+ "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for",
+ "function", "if", "import", "in", "instanceof", "new", "null", "return", "super",
+ "switch", "this", "throw", "true", "try", "typeof", "var", "void", "while", "with"
+ );
+ private final TypeResolver typeResolver;
+
+ public TsRenderer(TypeResolver typeResolver) {
+ this.typeResolver = typeResolver;
+ }
+
+ @Override
+ public String render(DocletModel model) {
+ Map tsAliases = buildTypeScriptAliases(model);
+ applyTypeScriptAliases(tsAliases);
+
+ List events = collectByGroup(model, ClassGroup.Event);
+ List libraries = collectByGroup(model, ClassGroup.Library);
+
+ StringBuilder out = new StringBuilder();
+ appendGlobalDeclarations(out);
+ appendEvents(out, events);
+ appendEventFilterers(out, events);
+ appendEventTypeMap(out, events);
+ appendLibraries(out, libraries);
+
+ out.append("\n\ndeclare ").append(renderPackages(model)).append("\n");
+ appendAliasTypes(out, model);
+ appendEnumTypes(out, model.declaredTypes());
+
+ return out.toString();
+ }
+
+ private void appendGlobalDeclarations(StringBuilder out) {
+ out.append("/**\n");
+ out.append(" * The global context\n");
+ out.append(" * If you're trying to access the context in {@link JsMacros.on},\n");
+ out.append(" * use the second param of callback\n");
+ out.append(" */\n");
+ out.append("declare const context: EventContainer;\n");
+ out.append("/**\n");
+ out.append(" * Assert and convert event type:\n");
+ out.append(" * ```js\n");
+ out.append(" * JsMacros.assertEvent(event, 'Service')\n");
+ out.append(" * ```\n");
+ out.append(" * If the type doesn't convert, that means the event type doesn't have any properties\n");
+ out.append(" */\n");
+ out.append("declare const event: Events.BaseEvent;\n");
+ out.append("declare const file: Packages.java.io.File;\n\n");
+ }
+
+ private void appendEvents(StringBuilder out, List events) {
+ out.append("declare namespace Events {\n\n");
+ indent(out, 1).append("interface BaseEvent extends JavaObject {\n\n");
+ indent(out, 2).append("getEventName(): string;\n\n");
+ indent(out, 1).append("}\n\n");
+ indent(out, 1).append("interface Cancellable {\n\n");
+ indent(out, 2).append("cancel(): void;\n\n");
+ indent(out, 1).append("}\n");
+
+ for (ClassDoc event : events) {
+ out.append("\n");
+ renderEventInterface(out, event, 1);
+ }
+ out.append("\n}\n");
+ }
+
+ private void appendEventFilterers(StringBuilder out, List events) {
+ out.append("\ninterface EventFilterers {\n");
+ for (ClassDoc event : events) {
+ if (event.eventFilterer() == null || event.eventFilterer().isBlank()) {
+ continue;
+ }
+ indent(out, 1).append(event.alias()).append(": ").append(event.eventFilterer()).append(";\n");
+ }
+ out.append("}\n");
+ }
+
+ private void appendEventTypeMap(StringBuilder out, List events) {
+ out.append("\ninterface Events {\n");
+ for (ClassDoc event : events) {
+ indent(out, 1).append(event.alias()).append(": Events.").append(event.alias()).append(";\n");
+ }
+ out.append("}\n");
+ }
+
+ private void appendLibraries(StringBuilder out, List libraries) {
+ for (ClassDoc library : libraries) {
+ out.append("\n");
+ renderLibraryNamespace(out, library, 0);
+ }
+ }
+
+ private void renderLibraryNamespace(StringBuilder out, ClassDoc library, int indent) {
+ appendDocComment(out, library.docComment(), List.of(), false, null, library, indent);
+ indent(out, indent).append("declare namespace ").append(library.alias()).append(" {\n");
+ for (MemberDoc member : library.members()) {
+ if (member.kind() != MemberKind.METHOD || hasModifier(member, "static")) {
+ continue;
+ }
+ appendDocComment(out, member.docComment(), member.params(), true, member, library, indent + 1);
+ indent(out, indent + 1).append("function ").append(member.name());
+ appendTypeParams(out, member.typeParams(), member.replaceTypeParams(), false);
+ out.append("(");
+ appendParams(out, member.params());
+ out.append(")");
+ out.append(": ").append(formatReturn(member, library));
+ out.append(";\n");
+ }
+ indent(out, indent).append("}\n");
+ }
+
+ private void renderEventInterface(StringBuilder out, ClassDoc event, int indent) {
+ appendDocComment(out, event.docComment(), List.of(), false, null, event, indent);
+ indent(out, indent).append("interface ").append(event.alias()).append(" extends BaseEvent");
+ if (event.eventCancellable()) {
+ out.append(", Cancellable");
+ }
+ out.append(" {\n");
+ for (MemberDoc member : event.members()) {
+ if (member.kind() == MemberKind.FIELD && !hasModifier(member, "static")) {
+ renderField(out, member, indent + 1, false, event);
+ } else if (member.kind() == MemberKind.METHOD && !hasModifier(member, "static")) {
+ renderMethod(out, member, indent + 1, false, event);
+ }
+ }
+ indent(out, indent).append("}\n");
+ }
+
+ private String renderPackages(DocletModel model) {
+ PackageNode root = buildTree(model);
+ PackageNode current = root;
+ StringBuilder name = new StringBuilder(root.name);
+ while (current.classes.isEmpty() && current.children.size() == 1) {
+ PackageNode child = current.children.values().iterator().next();
+ if (isReservedWord(child.name)) {
+ break;
+ }
+ name.append(".").append(child.name);
+ current = child;
+ }
+ StringBuilder out = new StringBuilder();
+ out.append("namespace ").append(name).append(" {\n");
+ renderPackageNode(out, current, 1);
+ out.append("}");
+ return out.toString();
+ }
+
+ private PackageNode buildTree(DocletModel model) {
+ PackageNode root = new PackageNode("Packages");
+ for (PackageDoc pkg : model.packages()) {
+ for (ClassDoc clz : pkg.classes()) {
+ root.addClass(pkg.name(), clz);
+ }
+ }
+ return root;
+ }
+
+ private void renderPackageNode(StringBuilder out, PackageNode node, int indent) {
+ for (PackageNode child : node.children.values()) {
+ PackageNode current = child;
+ StringBuilder mergedName = new StringBuilder(child.name);
+ while (current.classes.isEmpty() && current.children.size() == 1) {
+ PackageNode onlyChild = current.children.values().iterator().next();
+ if (isReservedWord(onlyChild.name)) {
+ break;
+ }
+ mergedName.append(".").append(onlyChild.name);
+ current = onlyChild;
+ }
+ String namespaceName = escapePackageName(mergedName.toString());
+ indent(out, indent).append("export namespace ").append(namespaceName).append(" {\n");
+ renderPackageNode(out, current, indent + 1);
+ indent(out, indent).append("}\n");
+ if (isReservedWord(child.name)) {
+ indent(out, indent).append("export { ").append(namespaceName).append(" as ")
+ .append(child.name).append(" };\n");
+ }
+ }
+ for (ClassDoc clz : node.classes) {
+ renderClass(out, clz, indent);
+ }
+ }
+
+ private void renderClass(StringBuilder out, ClassDoc clz, int indent) {
+ if (clz.kind() == ClassKind.INTERFACE) {
+ appendDocComment(out, clz.docComment(), List.of(), false, null, clz, indent);
+ indent(out, indent).append("export abstract class ").append(tsSafeName(clz.name()))
+ .append(" extends java.lang.Interface {\n");
+ appendClassHeader(out, clz, indent + 1);
+ renderStaticMembers(out, clz, indent + 1, clz);
+ indent(out, indent).append("}\n");
+
+ indent(out, indent).append("export interface ").append(tsSafeName(clz.name()));
+ appendTypeParams(out, clz.typeParams(), null, false);
+ appendImplements(out, clz);
+ out.append(" {\n");
+ renderInstanceMembers(out, clz, indent + 1, clz);
+ indent(out, indent).append("}\n");
+ return;
+ }
+
+ // Don't generate interface for Library classes (they're rendered as namespaces)
+ if (!clz.implementsTypes().isEmpty() && clz.group() != ClassGroup.Library) {
+ appendDocComment(out, clz.docComment(), List.of(), false, null, clz, indent);
+ indent(out, indent).append("export interface ").append(tsSafeName(clz.name()));
+ appendTypeParams(out, clz.typeParams(), null, false);
+ appendImplements(out, clz);
+ out.append(" {}\n");
+ } else {
+ appendDocComment(out, clz.docComment(), List.of(), false, null, clz, indent);
+ }
+
+ boolean hasConstructor = clz.members().stream().anyMatch(member -> member.kind() == MemberKind.CONSTRUCTOR);
+ indent(out, indent).append("export ").append(hasConstructor ? "class " : "abstract class ")
+ .append(tsSafeName(clz.name()));
+ appendTypeParams(out, clz.typeParams(), null, false);
+ appendExtends(out, clz);
+ out.append(" {\n");
+ appendClassHeader(out, clz, indent + 1);
+ renderStaticMembers(out, clz, indent + 1, clz);
+ renderConstructors(out, clz, indent + 1);
+ renderInstanceMembers(out, clz, indent + 1, clz);
+ indent(out, indent).append("}\n");
+ }
+
+ private void renderField(StringBuilder out, MemberDoc member, int indent, boolean includeStatic, ClassDoc owner) {
+ appendDocComment(out, member.docComment(), List.of(), false, member, owner, indent);
+ indent(out, indent);
+ if (includeStatic && hasModifier(member, "static")) {
+ out.append("static ");
+ }
+ if (hasModifier(member, "final")) {
+ out.append("readonly ");
+ }
+ out.append(member.name()).append(": ").append(formatReturn(member, owner)).append(";\n");
+ }
+
+ private void renderMethod(StringBuilder out, MemberDoc member, int indent, boolean includeStatic, ClassDoc owner) {
+ appendDocComment(out, member.docComment(), member.params(), true, member, owner, indent);
+ indent(out, indent);
+ if (includeStatic && hasModifier(member, "static")) {
+ out.append("static ");
+ }
+ out.append(member.name());
+ appendTypeParams(out, member.typeParams(), member.replaceTypeParams(), false);
+ out.append("(");
+ if (member.replaceParams() != null && !member.replaceParams().isBlank()) {
+ String replaced = member.replaceParams();
+ // Check if replaceParams contains complete declaration(s) with overloads
+ if (replaced.contains(");")) {
+ // It's a complete declaration with overloads, output as-is
+ out.append(replaced);
+ if (!replaced.endsWith("\n")) {
+ out.append("\n");
+ }
+ return;
+ }
+ // Otherwise it's just parameter replacement
+ out.append(replaced);
+ } else {
+ appendParams(out, member.params());
+ }
+ out.append(")");
+ out.append(": ").append(formatReturn(member, owner));
+ out.append(";\n");
+ }
+
+ private void renderConstructor(StringBuilder out, MemberDoc member, int indent, ClassDoc owner) {
+ appendDocComment(out, member.docComment(), member.params(), false, member, owner, indent);
+ indent(out, indent).append("constructor");
+ appendTypeParams(out, member.typeParams(), member.replaceTypeParams(), false);
+ out.append("(");
+ if (member.replaceParams() != null && !member.replaceParams().isBlank()) {
+ out.append(member.replaceParams());
+ } else {
+ appendParams(out, member.params());
+ }
+ out.append(");\n");
+ }
+
+ private void renderStaticMembers(StringBuilder out, ClassDoc clz, int indent, ClassDoc owner) {
+ for (MemberDoc member : clz.members()) {
+ if (!hasModifier(member, "static")) {
+ continue;
+ }
+ if (member.kind() == MemberKind.FIELD) {
+ renderField(out, member, indent, true, owner);
+ } else if (member.kind() == MemberKind.METHOD) {
+ renderMethod(out, member, indent, true, owner);
+ }
+ }
+ }
+
+ private void renderConstructors(StringBuilder out, ClassDoc clz, int indent) {
+ for (MemberDoc member : clz.members()) {
+ if (member.kind() == MemberKind.CONSTRUCTOR) {
+ renderConstructor(out, member, indent, clz);
+ }
+ }
+ }
+
+ private void renderInstanceMembers(StringBuilder out, ClassDoc clz, int indent, ClassDoc owner) {
+ for (MemberDoc member : clz.members()) {
+ if (hasModifier(member, "static")) {
+ continue;
+ }
+ if (member.kind() == MemberKind.FIELD) {
+ renderField(out, member, indent, false, owner);
+ } else if (member.kind() == MemberKind.METHOD) {
+ renderMethod(out, member, indent, false, owner);
+ }
+ }
+ }
+
+ private void appendParams(StringBuilder out, List params) {
+ boolean first = true;
+ for (ParamDoc param : params) {
+ if (!first) {
+ out.append(", ");
+ }
+ first = false;
+ if (param.varArgs()) {
+ out.append("...");
+ }
+ String name = escapeParamName(param.name());
+ out.append(name).append(": ");
+ if (param.varArgs()) {
+ String baseType = formatType(param.type(), true, false);
+ if (baseType.endsWith("[]")) {
+ baseType = baseType.substring(0, baseType.length() - "[]".length());
+ }
+ if (param.type().nullable()) {
+ baseType = baseType + " | null";
+ }
+ out.append("JavaVarArgs<").append(baseType).append(">");
+ } else {
+ out.append(formatType(param.type(), true, true));
+ }
+ }
+ }
+
+ private void appendTypeParams(
+ StringBuilder out,
+ List typeParams,
+ String replaceTypeParams,
+ boolean defaultToAny
+ ) {
+ if (replaceTypeParams != null && !replaceTypeParams.isBlank()) {
+ out.append("<").append(replaceTypeParams).append(">");
+ return;
+ }
+ if (typeParams == null || typeParams.isEmpty()) {
+ return;
+ }
+ out.append("<");
+ boolean first = true;
+ for (TypeRef param : typeParams) {
+ if (!first) {
+ out.append(", ");
+ }
+ first = false;
+ out.append(formatTypeParam(param, defaultToAny));
+ }
+ out.append(">");
+ }
+
+ private String formatTypeParam(TypeRef param, boolean defaultToAny) {
+ StringBuilder out = new StringBuilder(param.name());
+ String ext = param.bounds() == null ? "any" : formatType(param.bounds(), false, false);
+ if (!ext.endsWith("any")) {
+ out.append(" extends ").append(ext);
+ if (defaultToAny) {
+ out.append(" = any");
+ }
+ } else if (ext.startsWith("/* net.minecraft.")) {
+ out.append(" = ").append(ext);
+ } else if (defaultToAny) {
+ out.append(" = any");
+ }
+ return out.toString();
+ }
+
+ private String formatReturn(MemberDoc member, ClassDoc owner) {
+ if (member.replaceReturn() != null && !member.replaceReturn().isBlank()) {
+ return member.replaceReturn();
+ }
+ if (shouldReturnThis(member, owner)) {
+ return "this";
+ }
+ return formatType(member.returnType(), false, true);
+ }
+
+ private String formatType(TypeRef type, boolean paramType, boolean includeNull) {
+ String formatted = typeResolver.format(type, TargetLanguage.TYPESCRIPT, paramType);
+ if (includeNull && type.nullable()) {
+ return formatted + " | null";
+ }
+ return formatted;
+ }
+
+ private void appendAliasTypes(StringBuilder out, DocletModel model) {
+ List wagClasses = new ArrayList<>();
+ for (PackageDoc pkg : model.packages()) {
+ if (pkg.name().startsWith("com.jsmacrosce")) {
+ wagClasses.addAll(pkg.classes());
+ }
+ }
+ wagClasses.sort(Comparator.comparing(ClassDoc::name, String.CASE_INSENSITIVE_ORDER));
+ Set seen = new HashSet<>();
+ Set aliases = new TreeSet<>();
+ for (ClassDoc clz : wagClasses) {
+ if (!seen.add(clz.name())) {
+ continue;
+ }
+ String aliasName = buildAliasName(clz, true);
+ String aliasValue = formatClassType(clz);
+ aliases.add("type " + aliasName + " = " + aliasValue + ";");
+ }
+ for (String alias : aliases) {
+ out.append("\n").append(alias);
+ }
+ }
+
+ private String buildAliasName(ClassDoc clz, boolean defaultToAny) {
+ StringBuilder out = new StringBuilder(clz.name().replace(".", "$"));
+ if (clz.typeParams() != null && !clz.typeParams().isEmpty()) {
+ out.append("<");
+ boolean first = true;
+ for (TypeRef param : clz.typeParams()) {
+ if (!first) {
+ out.append(", ");
+ }
+ first = false;
+ out.append(formatTypeParam(param, defaultToAny));
+ }
+ out.append(">");
+ }
+ return out.toString();
+ }
+
+ private String formatClassType(ClassDoc clz) {
+ TypeRef classType = new TypeRef(
+ TypeKind.DECLARED,
+ clz.name(),
+ clz.qualifiedName(),
+ clz.typeParams(),
+ false,
+ false,
+ null,
+ false
+ );
+ return typeResolver.format(classType, TargetLanguage.TYPESCRIPT, false);
+ }
+
+ private void appendEnumTypes(StringBuilder out, List declaredTypes) {
+ out.append(
+ """
+
+ // Enum types
+ type Bit = 1 | 0;
+ type Trit = 2 | Bit;
+ type Dit = 3 | Trit;
+ type Pentit = 4 | Dit;
+ type Hexit = 5 | Pentit;
+ type Septit = 6 | Hexit;
+ type Octit = 7 | Septit;
+
+ type Side = Hexit;
+ type HotbarSlot = Octit | 8;
+ type HotbarSwapSlot = HotbarSlot | OffhandSlot;
+ type ClickSlotButton = HotbarSwapSlot | 9 | 10;
+ type OffhandSlot = 40;
+
+ """
+ );
+
+ for (DeclaredTypeDoc decl : declaredTypes) {
+ out.append("type ").append(decl.name()).append(" = ").append(decl.type());
+ if (!decl.type().contains("\n")) {
+ out.append(";");
+ }
+ out.append("\n");
+ }
+ }
+
+ private List collectByGroup(DocletModel model, ClassGroup group) {
+ List result = new ArrayList<>();
+ for (PackageDoc pkg : model.packages()) {
+ for (ClassDoc clz : pkg.classes()) {
+ if (clz.group() == group && clz.alias() != null) {
+ result.add(clz);
+ }
+ }
+ }
+ result.sort(
+ Comparator.comparing(ClassDoc::alias, Comparator.nullsLast(String.CASE_INSENSITIVE_ORDER))
+ .thenComparing(ClassDoc::name, String.CASE_INSENSITIVE_ORDER)
+ );
+ return result;
+ }
+
+ private Map buildTypeScriptAliases(DocletModel model) {
+ Map aliases = new HashMap<>();
+ aliases.put("com.jsmacrosce.jsmacros.core.event.BaseEvent", "Events.BaseEvent");
+ for (PackageDoc pkg : model.packages()) {
+ for (ClassDoc clz : pkg.classes()) {
+ if (clz.group() == ClassGroup.Event && clz.alias() != null) {
+ aliases.put(clz.qualifiedName(), "Events." + clz.alias());
+ } else if (clz.group() == ClassGroup.Library && clz.alias() != null) {
+ aliases.put(clz.qualifiedName(), "typeof " + clz.alias());
+ }
+ }
+ }
+ return aliases;
+ }
+
+ private void applyTypeScriptAliases(Map aliases) {
+ // TODO: This ignores all other aliases?
+ if (typeResolver instanceof BasicTypeResolver basicTypeResolver) {
+ basicTypeResolver.setTypeScriptAliases(aliases);
+ }
+ }
+
+ private StringBuilder indent(StringBuilder out, int indent) {
+ out.append(" ".repeat(Math.max(0, indent)));
+ return out;
+ }
+
+ private boolean hasModifier(MemberDoc member, String modifier) {
+ return member.modifiers().contains(modifier);
+ }
+
+ private String tsSafeName(String name) {
+ return name.replace('.', '$');
+ }
+
+ private String escapeParamName(String name) {
+ if (isReservedWord(name)) {
+ return "_" + name;
+ }
+ return name;
+ }
+
+ private String escapePackageName(String name) {
+ if (isReservedWord(name)) {
+ return "_" + name;
+ }
+ return name;
+ }
+
+ private boolean isReservedWord(String name) {
+ return TS_RESERVED_WORDS.contains(name);
+ }
+
+ private void appendClassHeader(StringBuilder out, ClassDoc clz, int indent) {
+ indent(out, indent).append("static readonly class: JavaClass<")
+ .append(buildClassHeaderType(clz)).append(">;\n");
+ indent(out, indent).append("/** @deprecated */ static prototype: undefined;\n");
+ }
+
+ private String buildClassHeaderType(ClassDoc clz) {
+ StringBuilder builder = new StringBuilder(tsSafeName(clz.name()));
+ int params = clz.typeParams().size();
+ if (params > 0) {
+ builder.append("<");
+ builder.append("any, ".repeat(params));
+ builder.setLength(builder.length() - 2);
+ builder.append(">");
+ }
+ return builder.toString();
+ }
+
+ private void appendExtends(StringBuilder out, ClassDoc clz) {
+ String extendsType;
+ if (clz.extendsTypes().isEmpty()) {
+ extendsType = "java.lang.Object";
+ } else {
+ extendsType = formatHeritageType(clz.extendsTypes().getFirst(), true);
+ }
+ out.append(" extends ").append(extendsType);
+ }
+
+ private void appendImplements(StringBuilder out, ClassDoc clz) {
+ if (clz.implementsTypes().isEmpty()) {
+ return;
+ }
+ out.append(" extends ");
+ boolean first = true;
+ for (TypeRef type : clz.implementsTypes()) {
+ if (!first) {
+ out.append(", ");
+ }
+ first = false;
+ out.append(formatHeritageType(type, false));
+ }
+ }
+
+ private String formatHeritageType(TypeRef type, boolean isExtends) {
+ String formatted = typeResolver.format(type, TargetLanguage.TYPESCRIPT, false);
+ if (isExtends) {
+ if (formatted.equals("any") || formatted.equals("JavaObject") || formatted.equals("Object")
+ || formatted.equals("void")) {
+ return "java.lang.Object";
+ }
+ if (formatted.startsWith("/* net.minecraft.") && formatted.endsWith("any")) {
+ return formatted.substring(0, formatted.length() - "any".length()) + "java.lang.Object";
+ }
+ return formatted;
+ }
+ if (formatted.startsWith("/* net.minecraft.") && formatted.endsWith("any")) {
+ return formatted.substring(0, formatted.length() - "any".length()) + "JavaObject";
+ }
+ return formatted;
+ }
+
+ private boolean shouldReturnThis(MemberDoc member, ClassDoc owner) {
+ if (owner == null || member.docComment() == null || member.kind() != MemberKind.METHOD) {
+ return false;
+ }
+ String returnText = getTagText(member.docComment(), DocTagKind.RETURN);
+ if (returnText.isBlank()) {
+ return false;
+ }
+ String trimmed = returnText.trim();
+ if (!trimmed.equals("self") && !trimmed.startsWith("self ")) {
+ return false;
+ }
+ TypeRef returnType = member.returnType();
+ return returnType != null && owner.qualifiedName().equals(returnType.qualifiedName());
+ }
+
+ private void appendDocComment(
+ StringBuilder out,
+ DocComment comment,
+ List params,
+ boolean includeReturn,
+ MemberDoc member,
+ ClassDoc owner,
+ int indent
+ ) {
+ if (comment == null) {
+ return;
+ }
+
+ // Render the body via DocBodyRenderer — links become {@link ConvertedSig}.
+ List bodyNodes = comment.body().isEmpty() ? comment.summary() : comment.body();
+ String desc = DocBodyRenderer.toPlainText(bodyNodes, this::resolveLinkForJsDoc);
+
+ List lines = new ArrayList<>();
+ if (!desc.isBlank()) {
+ lines.add(desc);
+ }
+
+ Map paramDocs = new HashMap<>();
+ for (DocTag tag : comment.tags()) {
+ if (tag.kind() == DocTagKind.PARAM && tag.name() != null) {
+ paramDocs.put(tag.name(), DocBodyRenderer.toPlainText(tag.body(), this::resolveLinkForJsDoc));
+ }
+ }
+ for (ParamDoc param : params) {
+ String text = paramDocs.get(param.name());
+ if (text != null && !text.isBlank()) {
+ lines.add("@param " + escapeParamName(param.name()) + " " + text);
+ }
+ }
+
+ if (includeReturn) {
+ String returnText = getTagText(comment, DocTagKind.RETURN);
+ if (!returnText.isBlank()) {
+ if (returnText.startsWith("{")) {
+ returnText = "{*} " + returnText;
+ }
+ lines.add("@return " + returnText);
+ } else if (shouldReturnThis(member, owner)) {
+ lines.add("@return self");
+ }
+ }
+
+ String since = getTagText(comment, DocTagKind.SINCE);
+ if (!since.isBlank()) {
+ lines.add("@since " + since);
+ }
+ String deprecated = getTagText(comment, DocTagKind.DEPRECATED);
+ if (hasDeprecatedTag(comment)) {
+ lines.add(deprecated.isBlank() ? "@deprecated" : "@deprecated " + deprecated);
+ }
+ for (DocTag tag : comment.tags()) {
+ if (tag.kind() == DocTagKind.SEE) {
+ String formatted = DocBodyRenderer.toPlainText(tag.body(), this::resolveLinkForJsDoc);
+ if (!formatted.isBlank()) {
+ lines.add("@see " + formatted);
+ }
+ }
+ }
+ for (DocTag tag : comment.tags()) {
+ if (tag.kind() == DocTagKind.TEMPLATE && tag.name() != null) {
+ String text = DocBodyRenderer.toPlainText(tag.body(), this::resolveLinkForJsDoc);
+ if (!text.isBlank()) {
+ lines.add("@template " + tag.name() + " " + text);
+ }
+ }
+ }
+ for (DocTag tag : comment.tags()) {
+ if (tag.kind() == DocTagKind.OTHER) {
+ String text = DocBodyRenderer.toPlainText(tag.body(), this::resolveLinkForJsDoc);
+ if (!text.isBlank()) {
+ lines.add(text);
+ }
+ }
+ }
+
+ if (lines.isEmpty()) {
+ return;
+ }
+ indent(out, indent).append("/**\n");
+ for (String line : lines) {
+ // Split on newlines to handle multi-line comments
+ String[] subLines = line.split("\n");
+ for (String subLine : subLines) {
+ indent(out, indent).append(" * ").append(subLine).append("\n");
+ }
+ }
+ indent(out, indent).append(" */\n");
+ }
+
+ /**
+ * Resolves a {@link DocBodyNode.Link} to the JSDoc {@code {@link}} format used
+ * in TypeScript declaration files. Simple Java types map to their TS aliases;
+ * all other signatures are converted via {@link DocBodyRenderer#convertSignature}.
+ */
+ private String resolveLinkForJsDoc(DocBodyNode.Link link) {
+ String sig = link.signature();
+ String mapped = DocBodyRenderer.mapSimpleLinkSignature(sig);
+ if (mapped != null) {
+ return mapped;
+ }
+ String converted = DocBodyRenderer.convertSignature(sig);
+ String label = link.label();
+ if (label != null && !label.isBlank() && !label.equals(converted)) {
+ return "{@link " + converted + " " + label + "}";
+ }
+ return "{@link " + converted + "}";
+ }
+
+ /**
+ * Returns the rendered plain-text of the first tag of {@code kind},
+ * or an empty string when absent.
+ */
+ private String getTagText(DocComment comment, DocTagKind kind) {
+ if (comment == null) {
+ return "";
+ }
+ for (DocTag tag : comment.tags()) {
+ if (tag.kind() == kind) {
+ return DocBodyRenderer.toPlainText(tag.body(), this::resolveLinkForJsDoc);
+ }
+ }
+ return "";
+ }
+
+ private boolean hasDeprecatedTag(DocComment comment) {
+ if (comment == null) {
+ return false;
+ }
+ return comment.tags().stream().anyMatch(tag -> tag.kind() == DocTagKind.DEPRECATED);
+ }
+
+ private static class PackageNode {
+ private final String name;
+ private final Map children = new TreeMap<>();
+ private final List classes = new ArrayList<>();
+
+ private PackageNode(String name) {
+ this.name = name;
+ }
+
+ private void addClass(String packageName, ClassDoc clz) {
+ if (packageName == null || packageName.isEmpty()) {
+ classes.add(clz);
+ return;
+ }
+ String[] parts = packageName.split("\\.");
+ PackageNode current = this;
+ for (String part : parts) {
+ current = current.children.computeIfAbsent(part, PackageNode::new);
+ }
+ current.classes.add(clz);
+ }
+ }
+}
diff --git a/buildSrc/src/main/java/com/jsmacrosce/doclet/core/tsdoclet/Main.java b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/tsdoclet/Main.java
new file mode 100644
index 000000000..9e6af1978
--- /dev/null
+++ b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/tsdoclet/Main.java
@@ -0,0 +1,84 @@
+package com.jsmacrosce.doclet.core.tsdoclet;
+
+import com.jsmacrosce.doclet.DocletIgnore;
+import com.sun.source.util.DocTrees;
+import jdk.javadoc.doclet.Doclet;
+import jdk.javadoc.doclet.DocletEnvironment;
+import jdk.javadoc.doclet.Reporter;
+import com.jsmacrosce.FileHandler;
+import com.jsmacrosce.doclet.core.BasicDocCommentParser;
+import com.jsmacrosce.doclet.core.BasicTypeResolver;
+import com.jsmacrosce.doclet.core.DocletModelBuilder;
+import com.jsmacrosce.doclet.core.render.TsRenderer;
+import com.jsmacrosce.doclet.options.IgnoredItem;
+import com.jsmacrosce.doclet.options.OutputDirectory;
+import com.jsmacrosce.doclet.options.Version;
+
+import javax.lang.model.SourceVersion;
+import javax.tools.Diagnostic;
+import java.io.File;
+import java.io.IOException;
+import java.util.*;
+
+@DocletIgnore
+public class Main implements Doclet {
+ public static Reporter reporter;
+ public static DocTrees treeUtils;
+
+ @Override
+ public void init(Locale locale, Reporter reporter) {
+ Main.reporter = reporter;
+ }
+
+ @Override
+ public String getName() {
+ return "TypeScript Generator";
+ }
+
+ @SuppressWarnings("SpellCheckingInspection")
+ @Override
+ public Set getSupportedOptions() {
+ return Set.of(
+ new Version(),
+ new OutputDirectory(),
+ new IgnoredItem("-doctitle", 1),
+ new IgnoredItem("-notimestamp", 0),
+ new IgnoredItem("-windowtitle", 1)
+ );
+ }
+
+ @Override
+ public SourceVersion getSupportedSourceVersion() {
+ return SourceVersion.RELEASE_16;
+ }
+
+ @Override
+ public boolean run(DocletEnvironment environment) {
+ treeUtils = environment.getDocTrees();
+
+ File outDir = OutputDirectory.outputDir;
+ if (outDir == null) {
+ reporter.print(Diagnostic.Kind.ERROR, "Output directory not set\n");
+ return false;
+ }
+ if (!outDir.exists() && !outDir.mkdirs()) {
+ reporter.print(Diagnostic.Kind.ERROR, "Failed to create version dir\n");
+ return false;
+ }
+
+ FileHandler outputTS = new FileHandler(new File(outDir, "JsMacros-" + Version.version + ".d.ts"));
+ BasicTypeResolver typeResolver = new BasicTypeResolver();
+ DocletModelBuilder builder = new DocletModelBuilder(typeResolver, new BasicDocCommentParser(treeUtils));
+ var model = builder.build(environment);
+ TsRenderer renderer = new TsRenderer(typeResolver);
+
+ try {
+ outputTS.write(renderer.render(model));
+ } catch (IOException e) {
+ reporter.print(Diagnostic.Kind.ERROR, "Failed to write TypeScript output: " + e.getMessage());
+ return false;
+ }
+ return true;
+ }
+
+}
diff --git a/buildSrc/src/main/java/com/jsmacrosce/doclet/core/util/DocBodyRenderer.java b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/util/DocBodyRenderer.java
new file mode 100644
index 000000000..32c703457
--- /dev/null
+++ b/buildSrc/src/main/java/com/jsmacrosce/doclet/core/util/DocBodyRenderer.java
@@ -0,0 +1,319 @@
+package com.jsmacrosce.doclet.core.util;
+
+import com.jsmacrosce.doclet.DocletIgnore;
+import com.jsmacrosce.doclet.core.model.DocBodyNode;
+
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.regex.Pattern;
+
+/**
+ * Utility class for rendering a {@code List} to a target-format string.
+ *
+ * Each renderer calls the appropriate static method and supplies a
+ * {@code linkResolver} lambda that converts a {@link DocBodyNode.Link} node into
+ * its rendered form (e.g. a Markdown hyperlink, a JSDoc {@code {@link}} token,
+ * or plain text).
+ *
+ *
Shared signature-conversion helpers ({@link #looksLikeSignature},
+ * {@link #convertSignature}, {@link #mapSimpleLinkSignature}) are provided here
+ * so they are not duplicated across renderers.
+ */
+@DocletIgnore
+public final class DocBodyRenderer {
+
+ // Java boxed number types that map to their primitive names in display text.
+ public static final Map JAVA_NUMBER_TYPES = Map.of(
+ "java.lang.Integer", "int",
+ "java.lang.Float", "float",
+ "java.lang.Long", "long",
+ "java.lang.Short", "short",
+ "java.lang.Character", "char",
+ "java.lang.Byte", "byte",
+ "java.lang.Double", "double",
+ "java.lang.Number", "number"
+ );
+
+ private static final Pattern HTML_LINK =
+ Pattern.compile("(.*?)", Pattern.DOTALL);
+
+ private DocBodyRenderer() {}
+
+ // -------------------------------------------------------------------------
+ // Public rendering entry points
+ // -------------------------------------------------------------------------
+
+ /**
+ * Renders nodes to a Markdown string.
+ *
+ * HTML structural tags ({@code
}, {@code
}, {@code
}) are
+ * converted to Markdown equivalents. Remaining HTML angle brackets are
+ * escaped to {@code <}/{@code >} so they render as literal text
+ * inside HTML blocks embedded in Markdown. {@code } tags in
+ * {@link DocBodyNode.Html} nodes are converted to Markdown links.
+ *
+ * @param nodes the body node list to render
+ * @param linkResolver called for each {@link DocBodyNode.Link} node; should
+ * return a Markdown link string (e.g. {@code "[label](url)"})
+ * or a plain fallback label when the link cannot be resolved
+ */
+ public static String toMarkdown(List nodes, Function linkResolver) {
+ if (nodes == null || nodes.isEmpty()) {
+ return "";
+ }
+ StringBuilder sb = new StringBuilder();
+ for (DocBodyNode node : nodes) {
+ switch (node) {
+ case DocBodyNode.Text(var value) -> sb.append(value);
+ case DocBodyNode.Code(var value) -> sb.append("`").append(value).append("`");
+ case DocBodyNode.Link link -> sb.append(linkResolver.apply(link));
+ case DocBodyNode.Html(var raw) -> sb.append(processHtmlForMarkdown(raw));
+ }
+ }
+ String result = sb.toString().trim();
+ if (result.isEmpty()) {
+ return "";
+ }
+
+ // Post-process the accumulated string:
+ // 1. Convert … that survived Html nodes to Markdown links.
+ result = HTML_LINK.matcher(result).replaceAll("[$2]($1)");
+ // 2. Escape remaining HTML angle brackets so they render as literal text
+ // when embedded inside HTML blocks in the VitePress Markdown output.
+ result = result.replace("<", "<").replace(">", ">");
+ // 3. Normalise line endings after paragraph tags.
+ result = result.replaceAll("(?<=[.,:;>]) ?\n", " \n");
+
+ return result.trim();
+ }
+
+ /**
+ * Renders nodes to a plain-text string suitable for JSDoc comments or
+ * Python docstrings.
+ *
+ * HTML structural tags are stripped or converted to whitespace. Angle
+ * brackets in remaining HTML are left as-is (JSDoc and Python docstrings
+ * are not HTML contexts). {@code } tags are converted to
+ * {@code [text](url)} Markdown notation (common in JSDoc-flavored comments).
+ *
+ * @param nodes the body node list to render
+ * @param linkResolver called for each {@link DocBodyNode.Link} node; should
+ * return the plain-text or inline representation of the link
+ */
+ public static String toPlainText(List nodes, Function linkResolver) {
+ if (nodes == null || nodes.isEmpty()) {
+ return "";
+ }
+ StringBuilder sb = new StringBuilder();
+ for (DocBodyNode node : nodes) {
+ switch (node) {
+ case DocBodyNode.Text(var value) -> sb.append(value);
+ case DocBodyNode.Code(var value) -> sb.append(value);
+ case DocBodyNode.Link link -> sb.append(linkResolver.apply(link));
+ case DocBodyNode.Html(var raw) -> sb.append(processHtmlForPlainText(raw));
+ }
+ }
+
+ String result = sb.toString().trim();
+ if (result.isEmpty()) {
+ return "";
+ }
+
+ // Convert surviving links to Markdown notation (JSDoc-friendly).
+ result = HTML_LINK.matcher(result).replaceAll("[$2]($1)");
+ return result.trim();
+ }
+
+ /**
+ * Renders nodes to an inline HTML string, suitable for embedding inside HTML
+ * elements such as {@code }, {@code
}, or {@code }.
+ *
+ * Links are rendered as {@code label} elements.
+ * Code spans are rendered as {@code value}.
+ * {@link DocBodyNode.Html} nodes are passed through as-is (their HTML is already
+ * valid in an HTML context).
+ * Angle brackets in plain text are HTML-escaped so they don't break the
+ * surrounding HTML structure.
+ *
+ * Use this method whenever the output will be placed inside a raw HTML block
+ * rather than a Markdown paragraph — Markdown link syntax ({@code [text](url)})
+ * does not render inside raw HTML in VitePress/Vue.
+ *
+ * @param nodes the body node list to render
+ * @param linkResolver called for each {@link DocBodyNode.Link} node; should
+ * return an {@code label} string, or a
+ * plain text/code fallback when the link cannot be resolved
+ */
+ public static String toHtml(List nodes, Function linkResolver) {
+ if (nodes == null || nodes.isEmpty()) {
+ return "";
+ }
+ StringBuilder sb = new StringBuilder();
+ for (DocBodyNode node : nodes) {
+ switch (node) {
+ case DocBodyNode.Text(var value) ->
+ // Escape angle brackets in plain text so they don't break surrounding HTML.
+ sb.append(value.replace("&", "&").replace("<", "<").replace(">", ">"));
+ case DocBodyNode.Code(var value) ->
+ sb.append(" |