Skip to content

Commit

Permalink
Add incubating annotation to javadocs including max version informati…
Browse files Browse the repository at this point in the history
…on. (#1565)

Add @Incubating along with the max version information "To be removed in a.b.c."
  • Loading branch information
ylee088 authored Dec 7, 2021
1 parent 0d18678 commit e850b46
Show file tree
Hide file tree
Showing 5 changed files with 95 additions and 0 deletions.
5 changes: 5 additions & 0 deletions changelog/@unreleased/pr-1565.v2.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
type: improvement
improvement:
description: Add incubating annotation and max version info to javadoc
links:
- https://github.com/palantir/conjure-java/pull/1565
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ public static String getJavaDocWithRequestLine(EndpointDefinition endpointDef) {
private static Optional<String> getJavaDocInternal(EndpointDefinition endpointDef, boolean includeRequestLine) {
Optional<String> depr = endpointDef.getDeprecated().map(Javadoc::getDeprecatedJavadoc);

Optional<String> incDoc = Javadoc.getIncubatingJavadoc(endpointDef.getTags());

Optional<String> docs = endpointDef.getDocs().map(Javadoc::render);

Optional<String> requestLine = Optional.empty();
Expand All @@ -52,6 +54,7 @@ private static Optional<String> getJavaDocInternal(EndpointDefinition endpointDe
requestLine.ifPresent(sb::append);
params.ifPresent(sb::append);
depr.ifPresent(sb::append);
incDoc.ifPresent(sb::append);
return sb.length() > 0 ? Optional.of(sb.toString()) : Optional.empty();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@
import com.palantir.conjure.spec.HttpMethod;
import com.palantir.conjure.spec.HttpPath;
import java.util.Optional;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.apache.commons.lang3.StringUtils;
import org.commonmark.node.Paragraph;
import org.commonmark.parser.Parser;
Expand Down Expand Up @@ -90,5 +93,20 @@ public static String getDeprecatedJavadoc(Documentation deprecationDocs) {
return "@deprecated " + render(deprecationDocs);
}

public static Optional<String> getIncubatingJavadoc(Set<String> endppointTags) {
Optional<String> incubatingMaxVersion = Optional.empty();
if (endppointTags.contains("incubating")) {
Pattern maxVersionPattern = Pattern.compile(".*To be removed (in|after) \\d+\\.\\d+\\.(\\d+|x).*");
incubatingMaxVersion = endppointTags.stream()
.filter(t -> {
Matcher matcher = maxVersionPattern.matcher(t);
return matcher.matches();
})
.findFirst()
.map(t -> "@Incubating " + t);
}
return incubatingMaxVersion;
}

private Javadoc() {}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
/*
* (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.palantir.conjure.java;

import static org.assertj.core.api.Assertions.assertThat;

import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableSet;
import com.google.common.util.concurrent.MoreExecutors;
import com.palantir.conjure.defs.Conjure;
import com.palantir.conjure.java.services.JerseyServiceGenerator;
import com.palantir.conjure.spec.ConjureDefinition;
import java.io.File;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import org.junit.jupiter.api.parallel.Execution;
import org.junit.jupiter.api.parallel.ExecutionMode;

@Execution(ExecutionMode.CONCURRENT)
public final class ServiceGeneratorTests extends TestBase {

@TempDir
public File folder;

private static String compiledFileContent(File srcDir, String clazz) throws IOException {
return new String(Files.readAllBytes(Paths.get(srcDir.getPath(), clazz)), StandardCharsets.UTF_8);
}

@Test
public void testConjureIncubatingJavadoc() throws IOException {
ConjureDefinition conjure =
Conjure.parse(ImmutableList.of(new File("src/test/resources/example-conjure-incubating.yml")));
File src = Files.createDirectory(folder.toPath().resolve("src")).toFile();
new GenerationCoordinator(
MoreExecutors.directExecutor(), ImmutableSet.of(new JerseyServiceGenerator(Options.empty())))
.emit(conjure, src);

// Generated files contain imports
assertThat(compiledFileContent(src, "test/api/with/imports/IncubatingEndpoint.java"))
.contains("* @Incubating To be removed after 1.2.x.");
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
services:
IncubatingEndpoint:
name: Test Service
package: test.api.with.imports
base-path: /catalog
endpoints:
testIncubatingJavadoc:
http: GET /testIncubatingJavadoc
tags: ["To be removed after 1.2.x.", "incubating"]

0 comments on commit e850b46

Please sign in to comment.