Examples with Examples com.google.copybara.doc.annotations.Examples used on opensource projects

Example 1 with Examples

use of com.google.copybara.doc.annotations.Examples in project copybara by google.

the class MarkdownGenerator method generateFunctionDocumentation.

private CharSequence generateFunctionDocumentation(TypeElement module, SkylarkModule skyModule, Element member) throws ElementException {
    StringBuilder sb = new StringBuilder();
    AnnotationHelper<SkylarkSignature> signature = annotationHelper(member, SkylarkSignature.class);
    if (signature == null || !(member instanceof VariableElement)) {
        return sb;
    }
    if (!signature.ann.documented()) {
        return sb;
    }
    String functionName = signature.ann.name();
    DeclaredType objectType = signature.getClassValue("objectType");
    if (objectType.toString().equals(module.toString())) {
        functionName = skyModule.name() + "." + functionName;
    }
    sb.append("<a id=\"").append(functionName).append("\" aria-hidden=\"true\"></a>\n");
    sb.append("### ").append(functionName).append("\n\n");
    sb.append(signature.ann.doc());
    sb.append("\n\n");
    // Create a string like `Origin foo(param, param2=Default)`
    sb.append("`");
    String returnTypeStr = skylarkTypeName(signature.getClassValue("returnType"));
    if (!returnTypeStr.equals("")) {
        sb.append(returnTypeStr).append(" ");
    }
    sb.append(functionName).append("(");
    List<AnnotationValue> params = signature.getValue("parameters");
    StringBuilder longDescription = new StringBuilder();
    int startIndex = firstParamIsSelf(module, skyModule, objectType) ? 1 : 0;
    for (int i = startIndex; i < params.size(); i++) {
        AnnotationHelper<Param> param = new AnnotationHelper<>(signature.ann.parameters()[i], (AnnotationMirror) params.get(i).getValue(), member);
        if (i > startIndex) {
            sb.append(", ");
        }
        sb.append(param.ann.name());
        String defaultValue = param.ann.defaultValue();
        if (!defaultValue.isEmpty()) {
            sb.append("=").append(defaultValue);
        }
        longDescription.append(param.ann.name()).append("|");
        longDescription.append("`").append(skylarkTypeNameGeneric(param.getClassValue("type"), param.getClassValue("generic1"))).append("`").append("<br><p>");
        longDescription.append(param.ann.doc());
        longDescription.append("</p>");
        longDescription.append("\n");
    }
    sb.append(")`\n\n");
    if (longDescription.length() > 0) {
        sb.append("#### Parameters:\n\n");
        sb.append("Parameter | Description\n");
        sb.append("--------- | -----------\n");
        sb.append(longDescription);
        sb.append("\n\n");
    }
    // Generate flags associated with an specific method
    sb.append(generateFlagsInfo(member));
    AnnotationHelper<Examples> examples = annotationHelper(member, Examples.class);
    AnnotationHelper<Example> singleExample = annotationHelper(member, Example.class);
    if (examples != null) {
        sb.append("#### Examples:\n\n");
        for (Example example : examples.ann.value()) {
            printExample(sb, example);
        }
    } else if (singleExample != null) {
        sb.append("#### Example:\n\n");
        printExample(sb, singleExample.ann);
    }
    return sb;
}

Example 2 with Examples

use of com.google.copybara.doc.annotations.Examples in project copybara by google.

the class ExamplesTest method testExamples.

@Test
public void testExamples() {
    SkylarkTestExecutor executor = getExecutor();
    ImmutableList.Builder<Result> resBuilder = ImmutableList.builder();
    for (Class<?> module : executor.getModules()) {
        for (Method method : module.getMethods()) {
            Examples examples = method.getAnnotation(Examples.class);
            ImmutableList<Example> samples;
            if (examples == null) {
                Example singleSample = method.getAnnotation(Example.class);
                if (singleSample != null) {
                    samples = ImmutableList.of(singleSample);
                } else {
                    continue;
                }
            } else {
                samples = ImmutableList.copyOf(examples.value());
            }
            resBuilder.addAll(checkExamples(executor, module, samples, method.getName()));
        }
    }
    ImmutableList<Result> result = resBuilder.build();
    // Normally we won't remove examples or modules. This checks that we don't go down. This
    // is the number of modules in Apr 2019. We can update this from time to time. It is not
    // critical to have an accurate number, but that we don't lose at least these.
    assertWithMessage("Less examples than expected").that(result.size()).isAtLeast(48);
    Set<? extends Class<?>> modules = result.stream().map(e -> e.cls).collect(Collectors.toSet());
    assertWithMessage("Less classes than expected: " + modules).that(modules.size()).isAtLeast(5);
    List<Result> errors = result.stream().filter(Result::isError).collect(Collectors.toList());
    assertWithMessage("Errors in examples(" + errors.size() + "):\n\n" + Joiner.on("\n-----------------------------\n").join(errors)).that(errors).isEmpty();
}