Add command params to javadoc

Author: kklisura

cdtp-definition-builder/src/main/java/com/github/kklisura/cdtp/definition/builder/support/protocol/builder/CommandBuilder.java

@@ -37,6 +37,11 @@ public class CommandBuilder {
 	private static final String EVENT_LISTENER_ARGUMENT_TYPE = "EventHandler";
 	private static final String EVENT_LISTENER_RESULT = "EventListener";
 
+	private static final String NEW_LINE = "\r\n";
+
+	private static final String COMMENT_PARAM = "@param";
+	private static final String EMPTY_SPACE = " ";
+
 	private String basePackageName;
 	private String typesPackageName;
 	private String eventPackageName;
@@ -175,8 +180,9 @@ private void addCommand(Command command, Domain domain, JavaInterfaceBuilder int
 				builders);
 
 		String returnType = buildReturnType(command, domain, interfaceBuilder, domainTypeResolver, builders);
+		String description = buildMethodParamDescription(command.getDescription(), command.getParameters());
 
-		interfaceBuilder.addMethod(method, command.getDescription(), methodParams, returnType);
+		interfaceBuilder.addMethod(method, description, methodParams, returnType);
 
 		if (Boolean.TRUE.equals(command.getDeprecated())) {
 			interfaceBuilder.addMethodAnnotation(method, DEPRECATED_ANNOTATION);
@@ -194,6 +200,29 @@ private void addCommand(Command command, Domain domain, JavaInterfaceBuilder int
 		}
 	}
 
+	private String buildMethodParamDescription(String description, List<Property> parameters) {
+		StringBuilder result = new StringBuilder();
+		if (StringUtils.isNotEmpty(description)) {
+			result.append(description);
+		}
+
+		if (CollectionUtils.isNotEmpty(parameters)) {
+			result.append(NEW_LINE);
+
+			for (Property property : parameters) {
+				result.append(NEW_LINE);
+				result.append(COMMENT_PARAM + EMPTY_SPACE);
+				result.append(property.getName());
+				if (StringUtils.isNotEmpty(property.getDescription())) {
+					result.append(EMPTY_SPACE);
+					result.append(property.getDescription());
+				}
+			}
+		}
+
+		return result.toString();
+	}
+
 	private String buildReturnType(Command command, Domain domain, JavaInterfaceBuilder interfaceBuilder,
 								   DomainTypeResolver domainTypeResolver, List<Builder> builders) {
 		List<Property> returns = command.getReturns();

cdtp-definition-builder/src/test/java/com/github/kklisura/cdtp/definition/builder/support/java/builder/impl/JavaInterfaceBuilderImplTest.java

@@ -163,7 +163,8 @@ public void testBasicInterfaceWithSimpleMethod() throws IOException {
 		expect(sourceRoot.add(capture(compilationUnitCapture)))
 				.andReturn(sourceRoot);
 
-		interfaceBuilder.addMethod("someMethod1", "Method description", Collections.emptyList(), null);
+		String description = "Method description\r\n\r\n@param test Test param\r\n@return Returns nothing";
+		interfaceBuilder.addMethod("someMethod1", description, Collections.emptyList(), null);
 
 		replayAll();
 
@@ -175,6 +176,9 @@ public void testBasicInterfaceWithSimpleMethod() throws IOException {
 				"\n" +
 				"    /**\n" +
 				"     * Method description\n" +
+				"     *\n" +
+				"     * @param test Test param\n" +
+				"     * @return Returns nothing\n" +
 				"     */\n" +
 				"    void someMethod1();" +
 				"\n" +

cdtp-definition-builder/src/test/java/com/github/kklisura/cdtp/definition/builder/support/protocol/builder/CommandBuilderTest.java

@@ -168,10 +168,12 @@ public void testBuildCommandWithMethodWithSimpleParams() {
 		final StringProperty stringParam = new StringProperty();
 		stringParam.setName("stringParam1");
 		stringParam.setDeprecated(Boolean.TRUE);
+		stringParam.setDescription("String param 1 description");
 
 		final NumberProperty numberParam = new NumberProperty();
 		numberParam.setName("numberParam1");
 		numberParam.setExperimental(Boolean.TRUE);
+		numberParam.setDescription("Number param 1 description");
 
 		final BooleanProperty booleanReturnParam = new BooleanProperty();
 		booleanReturnParam.setName("booleanReturn");
@@ -186,17 +188,19 @@ public void testBuildCommandWithMethodWithSimpleParams() {
 		interfaceBuilder.setJavaDoc("Description");
 
 		Capture<List<MethodParam>> methodParamCapture = Capture.newInstance();
-		interfaceBuilder.addMethod(eq("command"), eq("command description"), capture(methodParamCapture), eq("Boolean"));
+		Capture<String> methodDescriptionCapture = Capture.newInstance();
+		interfaceBuilder.addMethod(eq("command"), capture(methodDescriptionCapture), capture(methodParamCapture), eq("Boolean"));
 
 		interfaceBuilder.addParametrizedMethodAnnotation("command", "Returns", "booleanReturn");
 
-
 		replayAll();
 
 		assertEquals(interfaceBuilder, commandBuilder.build(domain, resolver));
 
 		verifyAll();
 
+		assertEquals("command description\r\n\r\n@param stringParam1 String param 1 description\r\n@param numberParam1 Number param 1 description", methodDescriptionCapture.getValue());
+
 		List<MethodParam> params = methodParamCapture.getValue();
 		assertEquals(2, params.size());
 		Assert.assertEquals(stringParam.getName(), params.get(0).getName());
@@ -231,6 +235,7 @@ public void testBuildCommandWithMethodWithComplexParams() throws InstantiationEx
 		arrayProperty.setName("enumParam1");
 		arrayProperty.setExperimental(Boolean.TRUE);
 		arrayProperty.setOptional(Boolean.TRUE);
+		arrayProperty.setDescription("enum param 1 description");
 
 		EnumArrayItem enumArrayItem = new EnumArrayItem();
 		enumArrayItem.setEnumValues(Arrays.asList("enum1", "enum2"));
@@ -254,11 +259,13 @@ public void testBuildCommandWithMethodWithComplexParams() throws InstantiationEx
 				.andReturn(interfaceBuilder);
 		interfaceBuilder.setJavaDoc("Description");
 
+		Capture<String> mandatoryMethodDescriptionCapture = Capture.newInstance();
 		Capture<List<MethodParam>> mandatoryMethodParamCapture = Capture.newInstance();
-		interfaceBuilder.addMethod(eq("command"), eq("command description"), capture(mandatoryMethodParamCapture), eq("Boolean"));
+		interfaceBuilder.addMethod(eq("command"), capture(mandatoryMethodDescriptionCapture), capture(mandatoryMethodParamCapture), eq("Boolean"));
 
+		Capture<String> allMethodDescriptionCapture = Capture.newInstance();
 		Capture<List<MethodParam>> allMethodParamCapture = Capture.newInstance();
-		interfaceBuilder.addMethod(eq("command"), eq("command description"), capture(allMethodParamCapture), eq("Boolean"));
+		interfaceBuilder.addMethod(eq("command"), capture(allMethodDescriptionCapture), capture(allMethodParamCapture), eq("Boolean"));
 
 		final ObjectType resolvedRefType = new ObjectType();
 		resolvedRefType.setId("TestRef");
@@ -290,6 +297,10 @@ public void testBuildCommandWithMethodWithComplexParams() throws InstantiationEx
 		assertEquals(javaEnumBuilder, builderList.get(0));
 		assertEquals(interfaceBuilder, builderList.get(1));
 
+		assertEquals("command description\r\n\r\n@param stringParam1", mandatoryMethodDescriptionCapture.getValue());
+
+		assertEquals("command description\r\n\r\n@param stringParam1\r\n@param enumParam1 enum param 1 description", allMethodDescriptionCapture.getValue());
+
 		List<MethodParam> mandatoryParams = mandatoryMethodParamCapture.getValue();
 		assertEquals(1, mandatoryParams.size());
 		assertEquals(refParam.getName(), mandatoryParams.get(0).getName());

cdtp-java-client/src/main/java/com/github/kklisura/cdtp/protocol/commands/Accessibility.java

@@ -12,13 +12,18 @@ public interface Accessibility {
 
 	/**
 	 * Fetches the accessibility node and partial accessibility tree for this DOM node, if it exists.
+	 *
+	 * @param nodeId ID of node to get the partial accessibility tree for.
 	 */
 	@Experimental
 	@Returns("nodes")
 	List<AXNode> getPartialAXTree(@ParamName("nodeId") Integer nodeId);
 
 	/**
 	 * Fetches the accessibility node and partial accessibility tree for this DOM node, if it exists.
+	 *
+	 * @param nodeId ID of node to get the partial accessibility tree for.
+	 * @param fetchRelatives Whether to fetch this nodes ancestors, siblings and children. Defaults to true.
 	 */
 	@Experimental
 	@Returns("nodes")

cdtp-java-client/src/main/java/com/github/kklisura/cdtp/protocol/commands/Animation.java

@@ -33,37 +33,55 @@ public interface Animation {
 
 	/**
 	 * Sets the playback rate of the document timeline.
+	 *
+	 * @param playbackRate Playback rate for animations on page
 	 */
 	void setPlaybackRate(@ParamName("playbackRate") Double playbackRate);
 
 	/**
 	 * Returns the current time of the an animation.
+	 *
+	 * @param id Id of animation.
 	 */
 	@Returns("currentTime")
 	Double getCurrentTime(@ParamName("id") String id);
 
 	/**
 	 * Sets the paused state of a set of animations.
+	 *
+	 * @param animations Animations to set the pause state of.
+	 * @param paused Paused state to set to.
 	 */
 	void setPaused(@ParamName("animations") List<String> animations, @ParamName("paused") Boolean paused);
 
 	/**
 	 * Sets the timing of an animation node.
+	 *
+	 * @param animationId Animation id.
+	 * @param duration Duration of the animation.
+	 * @param delay Delay of the animation.
 	 */
 	void setTiming(@ParamName("animationId") String animationId, @ParamName("duration") Double duration, @ParamName("delay") Double delay);
 
 	/**
 	 * Seek a set of animations to a particular time within each animation.
+	 *
+	 * @param animations List of animation ids to seek.
+	 * @param currentTime Set the current time of each animation.
 	 */
 	void seekAnimations(@ParamName("animations") List<String> animations, @ParamName("currentTime") Double currentTime);
 
 	/**
 	 * Releases a set of animations to no longer be manipulated.
+	 *
+	 * @param animations List of animation ids to seek.
 	 */
 	void releaseAnimations(@ParamName("animations") List<String> animations);
 
 	/**
 	 * Gets the remote object of the Animation.
+	 *
+	 * @param animationId Animation id.
 	 */
 	@Returns("remoteObject")
 	RemoteObject resolveAnimation(@ParamName("animationId") String animationId);

cdtp-java-client/src/main/java/com/github/kklisura/cdtp/protocol/commands/ApplicationCache.java

@@ -27,12 +27,16 @@ public interface ApplicationCache {
 
 	/**
 	 * Returns manifest URL for document in the given frame.
+	 *
+	 * @param frameId Identifier of the frame containing document whose manifest is retrieved.
 	 */
 	@Returns("manifestURL")
 	String getManifestForFrame(@ParamName("frameId") String frameId);
 
 	/**
 	 * Returns relevant application cache data for the document in given frame.
+	 *
+	 * @param frameId Identifier of the frame containing document whose application cache is retrieved.
 	 */
 	@Returns("applicationCache")
 	com.github.kklisura.cdtp.protocol.types.applicationcache.ApplicationCache getApplicationCacheForFrame(@ParamName("frameId") String frameId);

cdtp-java-client/src/main/java/com/github/kklisura/cdtp/protocol/commands/Audits.java

@@ -14,11 +14,19 @@ public interface Audits {
 
 	/**
 	 * Returns the response body and size if it were re-encoded with the specified settings. Only applies to images.
+	 *
+	 * @param requestId Identifier of the network request to get content for.
+	 * @param encoding The encoding to use.
 	 */
 	EncodedResponse getEncodedResponse(@ParamName("requestId") String requestId, @ParamName("encoding") Encoding encoding);
 
 	/**
 	 * Returns the response body and size if it were re-encoded with the specified settings. Only applies to images.
+	 *
+	 * @param requestId Identifier of the network request to get content for.
+	 * @param encoding The encoding to use.
+	 * @param quality The quality of the encoding (0-1). (defaults to 1)
+	 * @param sizeOnly Whether to only return the size information (defaults to false).
 	 */
 	EncodedResponse getEncodedResponse(@ParamName("requestId") String requestId, @ParamName("encoding") Encoding encoding, @Optional @ParamName("quality") Double quality, @Optional @ParamName("sizeOnly") Boolean sizeOnly);
 }

cdtp-java-client/src/main/java/com/github/kklisura/cdtp/protocol/commands/Browser.java

@@ -15,6 +15,8 @@ public interface Browser {
 
 	/**
 	 * Get the browser window that contains the devtools target.
+	 *
+	 * @param targetId Devtools agent host id.
 	 */
 	WindowForTarget getWindowForTarget(@ParamName("targetId") String targetId);
 
@@ -25,11 +27,16 @@ public interface Browser {
 
 	/**
 	 * Set position and/or size of the browser window.
+	 *
+	 * @param windowId Browser window id.
+	 * @param bounds New window bounds. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined with 'left', 'top', 'width' or 'height'. Leaves unspecified fields unchanged.
 	 */
 	void setWindowBounds(@ParamName("windowId") Integer windowId, @ParamName("bounds") Bounds bounds);
 
 	/**
 	 * Get position and size of the browser window.
+	 *
+	 * @param windowId Browser window id.
 	 */
 	@Returns("bounds")
 	Bounds getWindowBounds(@ParamName("windowId") Integer windowId);