Implement method return comments

Resolves: #73
cocolabs · Mar 13, 2021 · e43f561 · e43f561
2 parents 78905dd + a11b280
commit e43f561
Show file tree

Hide file tree

Showing 11 changed files with 227 additions and 41 deletions.
diff --git a/src/main/java/io/cocolabs/pz/zdoc/compile/LuaCompiler.java b/src/main/java/io/cocolabs/pz/zdoc/compile/LuaCompiler.java
@@ -29,9 +29,9 @@
 import io.cocolabs.pz.zdoc.doc.ZomboidLuaDoc;
 import io.cocolabs.pz.zdoc.element.IClass;
 import io.cocolabs.pz.zdoc.element.IField;
-import io.cocolabs.pz.zdoc.element.IMethod;
 import io.cocolabs.pz.zdoc.element.IParameter;
 import io.cocolabs.pz.zdoc.element.java.JavaClass;
+import io.cocolabs.pz.zdoc.element.java.JavaMethod;
 import io.cocolabs.pz.zdoc.element.lua.*;
 import io.cocolabs.pz.zdoc.logger.Logger;
 
@@ -219,17 +219,18 @@ public Set<ZomboidLuaDoc> compile() throws CompilerException {
 				Logger.debug("Compiled field %s", field.getName());
 			}
 			Set<LuaMethod> luaMethods = new HashSet<>();
-			for (IMethod method : javaDoc.getMethods())
+			for (JavaMethod method : javaDoc.getMethods())
 			{
 				List<LuaParameter> parameters = new ArrayList<>();
 				for (IParameter param : method.getParams())
 				{
 					LuaType paramClass = resolveLuaType(param.getType());
 					parameters.add(new LuaParameter(paramClass, param.getName()));
 				}
+				JavaMethod.ReturnType returnType = method.getReturnType();
 				luaMethods.add(LuaMethod.Builder.create(method.getName())
 						.withOwner(luaClass).withModifier(method.getModifier())
-						.withReturnType(resolveLuaType(method.getReturnType()))
+						.withReturnType(resolveLuaType(returnType), returnType.getComment())
 						.withParams(parameters).withVarArg(method.hasVarArg())
 						.withComment(method.getComment()).build());
 

diff --git a/src/main/java/io/cocolabs/pz/zdoc/doc/detail/MethodDetail.java b/src/main/java/io/cocolabs/pz/zdoc/doc/detail/MethodDetail.java
@@ -76,25 +76,47 @@ protected List<JavaMethod> parse() throws DetailParsingException {
 					commentBuilder.append('\n').append(commentBlocks.get(i).text());
 				}
 			}
-			// include override method documentation
-			boolean lastElementOverrideLabel = false;
-			for (Element blockListElement : blockList.getAllElements())
+			String returnTypeComment = "";
+			Elements listElements = blockList.getAllElements();
+			for (int i = 0; i < listElements.size(); i++)
 			{
-				String tagName = blockListElement.tagName();
-				if (blockListElement.className().equals("overrideSpecifyLabel"))
+				Element listElement = listElements.get(i);
+				String className = listElement.className();
+
+				// include override method documentation
+				if (className.equals("overrideSpecifyLabel"))
 				{
 					if (commentBuilder.length() > 0) {
 						commentBuilder.append('\n');
 					}
-					commentBuilder.append(blockListElement.text());
-					lastElementOverrideLabel = true;
+					commentBuilder.append(listElement.text());
+					// avoid accessing index out of bounds
+					if (i + 1 < listElements.size())
+					{
+						Element overrideLabelElement = listElements.get(i += 1);
+						if (!overrideLabelElement.tagName().equals("dd"))
+						{
+							String format = "Unexpected description list element '%s'";
+							Logger.error(String.format(format, overrideLabelElement));
+						}
+						else commentBuilder.append('\n').append(overrideLabelElement.text());
+					}
 				}
-				else if (lastElementOverrideLabel)
+				// include method return value documentation
+				else if (className.equals("returnLabel"))
 				{
-					if (tagName.equals("dd")) {
-						commentBuilder.append('\n').append(blockListElement.text());
+					// avoid accessing index out of bounds
+					if (i + 1 < listElements.size())
+					{
+						Element returnLabelElement = listElements.get(i += 1);
+						if (returnLabelElement.tagName().equals("dd")) {
+							returnTypeComment = returnLabelElement.text();
+						}
+						else {
+							String format = "Unexpected description list element '%s'";
+							Logger.error(String.format(format, returnLabelElement));
+						}
 					}
-					lastElementOverrideLabel = false;
 				}
 			}
 			String methodComment = commentBuilder.toString();
@@ -126,9 +148,8 @@ else if (lastElementOverrideLabel)
 				}
 			}
 			result.add(JavaMethod.Builder.create(signature.name)
-					.withReturnType(type).withModifier(signature.modifier)
-					.withParams(params).withVarArgs(isVarArgs)
-					.withComment(signature.comment).build());
+					.withReturnType(type, returnTypeComment).withModifier(signature.modifier)
+					.withParams(params).withVarArgs(isVarArgs).withComment(signature.comment).build());
 		}
 		return result;
 	}

diff --git a/src/main/java/io/cocolabs/pz/zdoc/element/IReturnType.java b/src/main/java/io/cocolabs/pz/zdoc/element/IReturnType.java
@@ -0,0 +1,23 @@
+/*
+ * ZomboidDoc - Lua library compiler for Project Zomboid
+ * Copyright (C) 2020-2021 Matthew Cain
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+package io.cocolabs.pz.zdoc.element;
+
+public interface IReturnType {
+
+	String getComment();
+}
diff --git a/src/main/java/io/cocolabs/pz/zdoc/element/java/JavaMethod.java b/src/main/java/io/cocolabs/pz/zdoc/element/java/JavaMethod.java
@@ -38,7 +38,7 @@
 public class JavaMethod implements IMethod {
 
 	private final String name;
-	private final JavaClass returnType;
+	private final ReturnType returnType;
 	private final List<JavaParameter> params;
 	private final MemberModifier modifier;
 	private final boolean hasVarArg;
@@ -47,7 +47,7 @@ public class JavaMethod implements IMethod {
 	public JavaMethod(Builder builder) {
 
 		this.name = builder.name;
-		this.returnType = builder.returnType != null ? builder.returnType : new JavaClass(void.class);
+		this.returnType = builder.returnType != null ? builder.returnType : new ReturnType(void.class);
 		this.modifier = builder.modifier != null ? builder.modifier : MemberModifier.UNDECLARED;
 		List<JavaParameter> jParams = builder.params != null ? builder.params : new ArrayList<>();
 		if (builder.hasVarArg)
@@ -90,7 +90,7 @@ public JavaMethod(Builder builder) {
 	public JavaMethod(Method method) {
 
 		this.name = method.getName();
-		this.returnType = new JavaClass(method.getReturnType());
+		this.returnType = new ReturnType(method.getReturnType());
 
 		List<JavaParameter> params = new ArrayList<>();
 		for (Parameter methodParam : method.getParameters()) {
@@ -131,7 +131,7 @@ public String toString() {
 	public static class Builder {
 
 		private final String name;
-		private @Nullable JavaClass returnType;
+		private @Nullable ReturnType returnType;
 		private @Nullable MemberModifier modifier;
 		private @Nullable List<JavaParameter> params;
 
@@ -146,13 +146,18 @@ public static Builder create(String name) {
 			return new Builder(name);
 		}
 
+		public Builder withReturnType(JavaClass type, String comment) {
+			returnType = new ReturnType(type, comment);
+			return this;
+		}
+
 		public Builder withReturnType(JavaClass type) {
-			returnType = type;
+			returnType = new ReturnType(type, "");
 			return this;
 		}
 
 		public Builder withReturnType(Class<?> type) {
-			returnType = new JavaClass(type);
+			returnType = new ReturnType(type);
 			return this;
 		}
 
@@ -186,6 +191,33 @@ public JavaMethod build() {
 		}
 	}
 
+	public static class ReturnType extends JavaClass {
+
+		private final String comment;
+
+		public ReturnType(Class<?> clazz, @Nullable List<JavaClass> typeParameters, String comment) {
+			super(clazz, typeParameters);
+			this.comment = comment;
+		}
+
+		public ReturnType(Class<?> clazz, @Nullable List<JavaClass> typeParameters) {
+			this(clazz, typeParameters, "");
+		}
+
+		public ReturnType(JavaClass clazz, String comment) {
+			this(clazz.getClazz(), clazz.getTypeParameters(), comment);
+		}
+
+		public ReturnType(Class<?> clazz) {
+			super(clazz);
+			this.comment = "";
+		}
+
+		public String getComment() {
+			return comment;
+		}
+	}
+
 	@Override
 	public String getName() {
 		return name;
@@ -202,7 +234,7 @@ public String getComment() {
 	}
 
 	@Override
-	public JavaClass getReturnType() {
+	public ReturnType getReturnType() {
 		return returnType;
 	}
 

diff --git a/src/main/java/io/cocolabs/pz/zdoc/element/lua/LuaMethod.java b/src/main/java/io/cocolabs/pz/zdoc/element/lua/LuaMethod.java
@@ -27,6 +27,7 @@
 import org.jetbrains.annotations.UnmodifiableView;
 
 import io.cocolabs.pz.zdoc.element.IMethod;
+import io.cocolabs.pz.zdoc.element.IReturnType;
 import io.cocolabs.pz.zdoc.element.mod.AccessModifierKey;
 import io.cocolabs.pz.zdoc.element.mod.MemberModifier;
 import io.cocolabs.pz.zdoc.lang.lua.EmmyLua;
@@ -43,7 +44,7 @@ public class LuaMethod implements IMethod, Annotated {
 	private final @Nullable LuaClass owner;
 
 	private final String name;
-	private final LuaType returnType;
+	private final ReturnType returnType;
 	private final List<LuaParameter> params;
 	private final MemberModifier modifier;
 	private final boolean hasVarArg;
@@ -54,7 +55,7 @@ private LuaMethod(Builder builder) {
 
 		this.name = EmmyLua.getSafeLuaName(builder.name);
 		this.owner = builder.owner;
-		this.returnType = builder.returnType != null ? builder.returnType : new LuaType("void");
+		this.returnType = builder.returnType != null ? builder.returnType : new ReturnType("void");
 		this.modifier = builder.modifier != null ? builder.modifier : MemberModifier.UNDECLARED;
 		this.params = Collections.unmodifiableList(builder.params);
 
@@ -198,7 +199,7 @@ public static class Builder {
 
 		private @Nullable LuaClass owner;
 		private @Nullable MemberModifier modifier;
-		private @Nullable LuaType returnType;
+		private @Nullable ReturnType returnType;
 
 		private List<LuaParameter> params = new ArrayList<>();
 		private boolean hasVarArg = false;
@@ -223,8 +224,13 @@ public Builder withModifier(MemberModifier modifier) {
 			return this;
 		}
 
+		public Builder withReturnType(LuaType returnType, String comment) {
+			this.returnType = new ReturnType(returnType, comment);
+			return this;
+		}
+
 		public Builder withReturnType(LuaType returnType) {
-			this.returnType = returnType;
+			this.returnType = new ReturnType(returnType, "");
 			return this;
 		}
 
@@ -247,4 +253,27 @@ public LuaMethod build() {
 			return new LuaMethod(this);
 		}
 	}
+
+	public static class ReturnType extends LuaType implements IReturnType {
+
+		private final String comment;
+
+		public ReturnType(String name, List<LuaType> otherTypes, String comment) {
+			super(name, otherTypes);
+			this.comment = comment;
+		}
+
+		public ReturnType(String name) {
+			super(name);
+			this.comment = "";
+		}
+
+		public ReturnType(LuaType type, String comment) {
+			this(type.name, type.getTypeParameters(), comment);
+		}
+
+		public String getComment() {
+			return comment;
+		}
+	}
 }
diff --git a/src/main/java/io/cocolabs/pz/zdoc/lang/lua/EmmyLuaReturn.java b/src/main/java/io/cocolabs/pz/zdoc/lang/lua/EmmyLuaReturn.java
@@ -19,7 +19,7 @@
 
 import java.util.regex.Pattern;
 
-import io.cocolabs.pz.zdoc.element.lua.LuaType;
+import io.cocolabs.pz.zdoc.element.lua.LuaMethod;
 
 /**
  * Use {@code @return} to specify the return type of a function
@@ -56,12 +56,8 @@ public class EmmyLuaReturn extends EmmyLua {
 			"^---\\s*@return\\s+(\\w+)(?:\\s*\\|\\s*(\\w+))?(?:\\s*@\\s*(.*))?\\s*$"
 	);
 
-	public EmmyLuaReturn(LuaType type, String comment) {
-		super("return", formatType(type), comment);
-	}
-
-	public EmmyLuaReturn(LuaType type) {
-		this(type, "");
+	public EmmyLuaReturn(LuaMethod.ReturnType type) {
+		super("return", formatType(type), type.getComment());
 	}
 
 	public static boolean isAnnotation(String text) {

diff --git a/src/test/java/io/cocolabs/pz/zdoc/compile/LuaCompilerTest.java b/src/test/java/io/cocolabs/pz/zdoc/compile/LuaCompilerTest.java
@@ -470,7 +470,7 @@ void shouldAvoidDuplicateTypeNamesWhenCompilingLua() throws CompilerException {
 		Assertions.assertEquals(luaFields, zLuaDocs.iterator().next().getFields());
 	}
 
-	@Test @Order(13)
+	@Test @Order(14)
 	void shouldFilterGlobalClassTypesFromGlobalTypesWhenCompilingLua() {
 
 		Set<LuaClass> expectedGlobalTypes = Sets.newHashSet(

diff --git a/src/test/java/io/cocolabs/pz/zdoc/doc/ZomboidLuaDocTest.java b/src/test/java/io/cocolabs/pz/zdoc/doc/ZomboidLuaDocTest.java
@@ -452,6 +452,47 @@ void shouldThrowExceptionWhenModifyingImmutableFields() {
 		);
 	}
 
+	@Test
+	void shouldWriteZomboidLuaDocMethodsWithValidReturnTypeComments() throws IOException {
+
+		Set<LuaMethod> luaMethods = new LinkedHashSet<>();
+		luaMethods.add(LuaMethod.Builder.create("getObject").withOwner(TEST_LUA_CLASS)
+				.withReturnType(new LuaType("Object"), "returns a simple object")
+				.build()
+		);
+		luaMethods.add(LuaMethod.Builder.create("getNumber").withOwner(TEST_LUA_CLASS)
+				.withReturnType(new LuaType("Number"), "returns a simple number")
+				.withParams(ImmutableList.of(
+						new LuaParameter(new LuaType("Object"), "param"))
+				).build()
+		);
+		luaMethods.add(LuaMethod.Builder.create("getString").withOwner(TEST_LUA_CLASS)
+				.withReturnType(new LuaType("String"), "returns a simple string")
+				.withVarArg(true).withParams(ImmutableList.of(
+						new LuaParameter(new LuaType("Object"), "varargs"))
+				).build()
+		);
+		ZomboidLuaDoc zDoc = new ZomboidLuaDoc(
+				TEST_LUA_CLASS, new ArrayList<>(), luaMethods
+		);
+		List<String> expectedResult = ImmutableList.of(
+				"---@class ZomboidLuaDocTest : io.cocolabs.pz.zdoc.doc.ZomboidLuaDocTest",
+				"ZomboidLuaDocTest = {}",
+				"",
+				"---@return Object @returns a simple object",
+				"function ZomboidLuaDocTest:getObject() end",
+				"",
+				"---@param param Object",
+				"---@return Number @returns a simple number",
+				"function ZomboidLuaDocTest:getNumber(param) end",
+				"",
+				"---@vararg Object",
+				"---@return String @returns a simple string",
+				"function ZomboidLuaDocTest:getString(...) end"
+		);
+		Assertions.assertEquals(expectedResult, writeToFileAndRead(zDoc));
+	}
+
 	@TestOnly
 	private List<String> writeToFileAndRead(ZomboidLuaDoc zDoc) throws IOException {