org.apache.flink.annotation.docs.Documentation Java Examples

The following examples show how to use org.apache.flink.annotation.docs.Documentation. You can vote up the ones you like or vote down the ones you don't like, and go to the original project or source file by following the links above each example. You may check out the related API usage on the sidebar.
Example #1
Source File: ConfigOptionsDocGenerator.java    From Flink-CEPplus with Apache License 2.0 6 votes vote down vote up 
@VisibleForTesting
static void generateCommonSection(String rootDir, String outputDirectory, OptionsClassLocation[] locations, String pathPrefix) throws IOException, ClassNotFoundException {
	List<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	for (OptionsClassLocation location : locations) {
		commonOptions.addAll(findCommonOptions(rootDir, location.getModule(), location.getPackage(), pathPrefix));
	}
	commonOptions.sort((o1, o2) -> {
		int position1 = o1.field.getAnnotation(Documentation.CommonOption.class).position();
		int position2 = o2.field.getAnnotation(Documentation.CommonOption.class).position();
		if (position1 == position2) {
			return o1.option.key().compareTo(o2.option.key());
		} else {
			return Integer.compare(position1, position2);
		}
	});

	String commonHtmlTable = toHtmlTable(commonOptions);
	Files.write(Paths.get(outputDirectory, COMMON_SECTION_FILE_NAME), commonHtmlTable.getBytes(StandardCharsets.UTF_8));
}
Example #2
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 6 votes vote down vote up 
@VisibleForTesting
static void generateCommonSection(String rootDir, String outputDirectory, OptionsClassLocation[] locations, String pathPrefix) throws IOException, ClassNotFoundException {
	List<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	for (OptionsClassLocation location : locations) {
		commonOptions.addAll(findCommonOptions(rootDir, location.getModule(), location.getPackage(), pathPrefix));
	}
	commonOptions.sort((o1, o2) -> {
		int position1 = o1.field.getAnnotation(Documentation.CommonOption.class).position();
		int position2 = o2.field.getAnnotation(Documentation.CommonOption.class).position();
		if (position1 == position2) {
			return o1.option.key().compareTo(o2.option.key());
		} else {
			return Integer.compare(position1, position2);
		}
	});

	String commonHtmlTable = toHtmlTable(commonOptions);
	Files.write(Paths.get(outputDirectory, COMMON_SECTION_FILE_NAME), commonHtmlTable.getBytes(StandardCharsets.UTF_8));
}
Example #3
Source File: ConfigOptionsDocGenerator.java    From Flink-CEPplus with Apache License 2.0 5 votes vote down vote up 
private static Collection<OptionWithMetaInfo> findCommonOptions(String rootDir, String module, String packageName, String pathPrefix) throws IOException, ClassNotFoundException {
	Collection<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	processConfigOptions(rootDir, module, packageName, pathPrefix, optionsClass -> extractConfigOptions(optionsClass).stream()
		.filter(optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null)
		.forEachOrdered(commonOptions::add));
	return commonOptions;
}
Example #4
Source File: ConfigOptionsDocsCompletenessITCase.java    From Flink-CEPplus with Apache License 2.0 5 votes vote down vote up 
@Test
public void testCommonSectionCompleteness() throws IOException, ClassNotFoundException {
	Map<String, DocumentedOption> documentedOptions = parseDocumentedCommonOptions();
	Map<String, ExistingOption> existingOptions = findExistingOptions(
		optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null);

	compareDocumentedAndExistingOptions(documentedOptions, existingOptions);
}
Example #5
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 5 votes vote down vote up 
private static Collection<OptionWithMetaInfo> findCommonOptions(String rootDir, String module, String packageName, String pathPrefix) throws IOException, ClassNotFoundException {
	Collection<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	processConfigOptions(rootDir, module, packageName, pathPrefix, optionsClass -> extractConfigOptions(optionsClass).stream()
		.filter(optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null)
		.forEachOrdered(commonOptions::add));
	return commonOptions;
}
Example #6
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 5 votes vote down vote up 
/**
 * Transforms option to table row.
 *
 * @param optionWithMetaInfo option to transform
 * @return row with the option description
 */
private static String toHtmlString(final OptionWithMetaInfo optionWithMetaInfo) {
	ConfigOption<?> option = optionWithMetaInfo.option;
	String defaultValue = stringifyDefault(optionWithMetaInfo);
	Documentation.TableOption tableOption = optionWithMetaInfo.field.getAnnotation(Documentation.TableOption.class);
	StringBuilder execModeStringBuilder = new StringBuilder();
	if (tableOption != null) {
		Documentation.ExecMode execMode = tableOption.execMode();
		if (Documentation.ExecMode.BATCH_STREAMING.equals(execMode)) {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.BATCH.toString())
					.append("</span> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.STREAMING.toString())
					.append("</span>");
		} else {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(execMode.toString())
					.append("</span>");
		}
	}

	return "" +
		"        <tr>\n" +
		"            <td><h5>" + escapeCharacters(option.key()) + "</h5>" + execModeStringBuilder.toString() + "</td>\n" +
		"            <td style=\"word-wrap: break-word;\">" + escapeCharacters(addWordBreakOpportunities(defaultValue)) + "</td>\n" +
		"            <td>" + formatter.format(option.description()) + "</td>\n" +
		"        </tr>\n";
}
Example #7
Source File: ConfigOptionsDocsCompletenessITCase.java    From flink with Apache License 2.0 5 votes vote down vote up 
@Test
public void testCommonSectionCompleteness() throws IOException, ClassNotFoundException {
	Map<String, DocumentedOption> documentedOptions = parseDocumentedCommonOptions();
	Map<String, ExistingOption> existingOptions = findExistingOptions(
		optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null);

	compareDocumentedAndExistingOptions(documentedOptions, existingOptions);
}
Example #8
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 5 votes vote down vote up 
private static Collection<OptionWithMetaInfo> findSectionOptions(String rootDir, String module, String packageName, String pathPrefix) throws IOException, ClassNotFoundException {
	Collection<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	processConfigOptions(rootDir, module, packageName, pathPrefix, optionsClass -> extractConfigOptions(optionsClass).stream()
		.filter(optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.Section.class) != null)
		.forEachOrdered(commonOptions::add));
	return commonOptions;
}
Example #9
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 5 votes vote down vote up 
/**
 * Transforms option to table row.
 *
 * @param optionWithMetaInfo option to transform
 * @return row with the option description
 */
private static String toHtmlString(final OptionWithMetaInfo optionWithMetaInfo) {
	ConfigOption<?> option = optionWithMetaInfo.option;
	String defaultValue = stringifyDefault(optionWithMetaInfo);
	String type = typeToHtml(optionWithMetaInfo);
	Documentation.TableOption tableOption = optionWithMetaInfo.field.getAnnotation(Documentation.TableOption.class);
	StringBuilder execModeStringBuilder = new StringBuilder();
	if (tableOption != null) {
		Documentation.ExecMode execMode = tableOption.execMode();
		if (Documentation.ExecMode.BATCH_STREAMING.equals(execMode)) {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.BATCH.toString())
					.append("</span> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.STREAMING.toString())
					.append("</span>");
		} else {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(execMode.toString())
					.append("</span>");
		}
	}

	return "" +
		"        <tr>\n" +
		"            <td><h5>" + escapeCharacters(option.key()) + "</h5>" + execModeStringBuilder.toString() + "</td>\n" +
		"            <td style=\"word-wrap: break-word;\">" + escapeCharacters(addWordBreakOpportunities(defaultValue)) + "</td>\n" +
		"            <td>" + type + "</td>\n" +
		"            <td>" + formatter.format(option.description()) + "</td>\n" +
		"        </tr>\n";
}
Example #10
Source File: ConfigOptionsDocGenerator.java    From Flink-CEPplus with Apache License 2.0 4 votes vote down vote up 
private static boolean shouldBeDocumented(Field field) {
	return field.getAnnotation(Deprecated.class) == null &&
		field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
Example #11
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 4 votes vote down vote up 
private static boolean shouldBeDocumented(Field field) {
	return field.getAnnotation(Deprecated.class) == null &&
		field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
Example #12
Source File: RestAPIDocGenerator.java    From flink with Apache License 2.0 4 votes vote down vote up 
private static boolean shouldBeDocumented(MessageHeaders spec) {
	return spec.getClass().getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
Example #13
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 4 votes vote down vote up 
@VisibleForTesting
static void generateCommonSection(String rootDir, String outputDirectory, OptionsClassLocation[] locations, String pathPrefix) throws IOException, ClassNotFoundException {
	List<OptionWithMetaInfo> allSectionOptions = new ArrayList<>(32);
	for (OptionsClassLocation location : locations) {
		allSectionOptions.addAll(findSectionOptions(rootDir, location.getModule(), location.getPackage(), pathPrefix));
	}

	Map<String, List<OptionWithMetaInfo>> optionsGroupedBySection = allSectionOptions.stream()
		.flatMap(option -> {
			final String[] sections = option.field.getAnnotation(Documentation.Section.class).value();
			if (sections.length == 0) {
				throw new RuntimeException(String.format(
					"Option %s is annotated with %s but the list of sections is empty.",
					option.option.key(),
					Documentation.Section.class.getSimpleName()));
			}

			return Arrays.stream(sections).map(section -> Tuple2.of(section, option));
		})
		.collect(Collectors.groupingBy(option -> option.f0, Collectors.mapping(option -> option.f1, Collectors.toList())));

	optionsGroupedBySection.forEach(
		(section, options) -> {
			options.sort((o1, o2) -> {
				int position1 = o1.field.getAnnotation(Documentation.Section.class).position();
				int position2 = o2.field.getAnnotation(Documentation.Section.class).position();
				if (position1 == position2) {
					return o1.option.key().compareTo(o2.option.key());
				} else {
					return Integer.compare(position1, position2);
				}
			});

			String sectionHtmlTable = toHtmlTable(options);
			try {
				Files.write(Paths.get(outputDirectory, getSectionFileName(section)), sectionHtmlTable.getBytes(StandardCharsets.UTF_8));
			} catch (Exception e) {
				throw new RuntimeException(e);
			}
		}
	);
}
Example #14
Source File: ConfigOptionsDocGenerator.java    From flink with Apache License 2.0 4 votes vote down vote up 
private static boolean shouldBeDocumented(Field field) {
	return field.getAnnotation(Deprecated.class) == null &&
		field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
Example #15
Source File: ConfigOptionsDocsCompletenessITCase.java    From flink with Apache License 2.0 4 votes vote down vote up 
private static boolean isSuffixOption(Field field) {
	final Class<?> containingOptionsClass = field.getDeclaringClass();

	return field.getAnnotation(Documentation.SuffixOption.class) != null ||
		containingOptionsClass.getAnnotation(Documentation.SuffixOption.class) != null;
}