Search in sources :

Example 1 with DocExample

use of com.google.copybara.doc.DocBase.DocExample in project copybara by google.

the class ModuleLoader method processStarlarkMethod.

private DocFunction processStarlarkMethod(Method method, StarlarkMethod annotation, @Nullable String prefix) {
    Type[] genericParameterTypes = method.getGenericParameterTypes();
    Param[] starlarkParams = annotation.parameters();
    if (genericParameterTypes.length < starlarkParams.length) {
        throw new IllegalStateException(String.format("Missing java parameters for: %s\n" + "%s\n" + "%s", method, Arrays.toString(genericParameterTypes), Arrays.toString(starlarkParams)));
    }
    ImmutableList.Builder<DocParam> params = ImmutableList.builder();
    Map<String, DocDefault> docDefaultsMap = stream(method.getAnnotationsByType(DocDefault.class)).collect(Collectors.toMap(DocDefault::field, identity(), (f, v) -> v));
    for (int i = 0; i < starlarkParams.length; i++) {
        Type parameterType = genericParameterTypes[i];
        Param starlarkParam = starlarkParams[i];
        // Compute the list of names of allowed types (e.g. string or bool or NoneType).
        List<String> allowedTypeNames = new ArrayList<>();
        if (starlarkParam.allowedTypes().length > 0) {
            for (ParamType param : starlarkParam.allowedTypes()) {
                allowedTypeNames.add(skylarkTypeName(param.type()) + (param.generic1() != Object.class ? " of " + skylarkTypeName(param.generic1()) : ""));
            }
        } else {
            // Otherwise use the type of the parameter variable itself.
            allowedTypeNames.add(skylarkTypeName(parameterType));
        }
        DocDefault fieldInfo = docDefaultsMap.get(starlarkParam.name());
        if (fieldInfo != null && fieldInfo.allowedTypes().length > 0) {
            allowedTypeNames = Arrays.asList(fieldInfo.allowedTypes());
        }
        params.add(new DocParam(starlarkParam.name(), fieldInfo != null ? fieldInfo.value() : emptyToNull(starlarkParam.defaultValue()), allowedTypeNames, starlarkParam.doc()));
    }
    String returnType = method.getGenericReturnType().equals(NoneType.class) || method.getGenericReturnType().equals(void.class) ? null : skylarkTypeName(method.getGenericReturnType());
    return new DocFunction(prefix != null ? prefix + "." + annotation.name() : annotation.name(), annotation.doc(), returnType, params.build(), generateFlagsInfo(method), stream(method.getAnnotationsByType(Example.class)).map(DocExample::new).collect(toImmutableList()));
}
Also used : UsesFlags(com.google.copybara.doc.annotations.UsesFlags) DocExample(com.google.copybara.doc.DocBase.DocExample) Arrays(java.util.Arrays) DocFlag(com.google.copybara.doc.DocBase.DocFlag) HtmlEscapers(com.google.common.html.HtmlEscapers) DurationConverter(com.google.copybara.jcommander.DurationConverter) DocDefault(com.google.copybara.doc.annotations.DocDefault) CharStreams(com.google.common.io.CharStreams) Map(java.util.Map) ZipFile(java.util.zip.ZipFile) Splitter(com.google.common.base.Splitter) Method(java.lang.reflect.Method) ZipEntry(java.util.zip.ZipEntry) Param(net.starlark.java.annot.Param) DocModule(com.google.copybara.doc.DocBase.DocModule) ImmutableList.toImmutableList(com.google.common.collect.ImmutableList.toImmutableList) Collection(java.util.Collection) Collectors(java.util.stream.Collectors) List(java.util.List) StarlarkMethod(net.starlark.java.annot.StarlarkMethod) Type(java.lang.reflect.Type) NoneType(net.starlark.java.eval.NoneType) Function.identity(java.util.function.Function.identity) Pattern(com.google.re2j.Pattern) Annotation(java.lang.annotation.Annotation) Optional(java.util.Optional) DocFunction(com.google.copybara.doc.DocBase.DocFunction) DocSignaturePrefix(com.google.copybara.doc.annotations.DocSignaturePrefix) DocField(com.google.copybara.doc.DocBase.DocField) Arrays.stream(java.util.Arrays.stream) SortedMap(java.util.SortedMap) Joiner(com.google.common.base.Joiner) AnnotatedElement(java.lang.reflect.AnnotatedElement) Library(com.google.copybara.doc.annotations.Library) Matcher(com.google.re2j.Matcher) Parameter(com.beust.jcommander.Parameter) WildcardType(java.lang.reflect.WildcardType) StarlarkBuiltin(net.starlark.java.annot.StarlarkBuiltin) ArrayList(java.util.ArrayList) Example(com.google.copybara.doc.annotations.Example) ImmutableList(com.google.common.collect.ImmutableList) DocParam(com.google.copybara.doc.DocBase.DocParam) ParamType(net.starlark.java.annot.ParamType) Starlark(net.starlark.java.eval.Starlark) Nullable(javax.annotation.Nullable) UTF_8(java.nio.charset.StandardCharsets.UTF_8) IOException(java.io.IOException) Field(java.lang.reflect.Field) InputStreamReader(java.io.InputStreamReader) Strings.emptyToNull(com.google.common.base.Strings.emptyToNull) ParameterizedType(java.lang.reflect.ParameterizedType) TreeMap(java.util.TreeMap) ImmutableList.toImmutableList(com.google.common.collect.ImmutableList.toImmutableList) ImmutableList(com.google.common.collect.ImmutableList) DocDefault(com.google.copybara.doc.annotations.DocDefault) ArrayList(java.util.ArrayList) DocFunction(com.google.copybara.doc.DocBase.DocFunction) ParamType(net.starlark.java.annot.ParamType) Type(java.lang.reflect.Type) NoneType(net.starlark.java.eval.NoneType) WildcardType(java.lang.reflect.WildcardType) ParamType(net.starlark.java.annot.ParamType) ParameterizedType(java.lang.reflect.ParameterizedType) DocExample(com.google.copybara.doc.DocBase.DocExample) Param(net.starlark.java.annot.Param) DocParam(com.google.copybara.doc.DocBase.DocParam) DocParam(com.google.copybara.doc.DocBase.DocParam)

Example 2 with DocExample

use of com.google.copybara.doc.DocBase.DocExample in project copybara by google.

the class MarkdownRenderer method module.

private CharSequence module(DocModule module, int level) {
    StringBuilder sb = new StringBuilder();
    sb.append(title(level, module.name));
    sb.append(module.description).append("\n\n");
    if (!module.fields.isEmpty()) {
        sb.append(title(level + 2, "Fields:"));
        sb.append(tableHeader("Name", "Description"));
        for (DocField field : module.fields) {
            sb.append(tableRow(field.name, String.format("%s<br><p>%s</p>", typeName(field.type), field.description)));
        }
        sb.append("\n");
    }
    sb.append(flags(module.flags));
    for (DocFunction func : module.functions) {
        sb.append("<a id=\"").append(func.name).append("\" aria-hidden=\"true\"></a>");
        sb.append(title(level + 1, func.name));
        sb.append(func.description);
        sb.append("\n\n");
        if (func.returnType != null) {
            sb.append(typeName(func.returnType)).append(" ");
        }
        sb.append("`").append(func.name).append("(");
        Joiner.on(", ").appendTo(sb, Lists.transform(func.params, p -> p.name + (p.defaultValue == null ? "" : "=" + p.defaultValue)));
        sb.append(")`\n\n");
        if (!func.params.isEmpty()) {
            sb.append(title(level + 2, "Parameters:"));
            sb.append(tableHeader("Parameter", "Description"));
            for (DocParam param : func.params) {
                sb.append(tableRow(param.name, String.format("%s<br><p>%s</p>", param.allowedTypes.stream().map(this::typeName).collect(joining(" or ")), param.description)));
            }
            sb.append("\n");
        }
        if (!func.examples.isEmpty()) {
            sb.append(title(level + 2, func.examples.size() == 1 ? "Example:" : "Examples:"));
            for (DocExample example : func.examples) {
                sb.append(example(level + 3, example.example));
            }
            sb.append("\n");
        }
        sb.append(flags(func.flags));
    }
    return sb;
}
Also used : DocModule(com.google.copybara.doc.DocBase.DocModule) DocExample(com.google.copybara.doc.DocBase.DocExample) DocFlag(com.google.copybara.doc.DocBase.DocFlag) Ascii(com.google.common.base.Ascii) Collection(java.util.Collection) Set(java.util.Set) Collectors.joining(java.util.stream.Collectors.joining) HashSet(java.util.HashSet) Strings(com.google.common.base.Strings) Lists(com.google.common.collect.Lists) Example(com.google.copybara.doc.annotations.Example) DocParam(com.google.copybara.doc.DocBase.DocParam) Preconditions(com.google.common.base.Preconditions) DocFunction(com.google.copybara.doc.DocBase.DocFunction) DocField(com.google.copybara.doc.DocBase.DocField) Arrays.stream(java.util.Arrays.stream) Joiner(com.google.common.base.Joiner) DocExample(com.google.copybara.doc.DocBase.DocExample) DocFunction(com.google.copybara.doc.DocBase.DocFunction) DocField(com.google.copybara.doc.DocBase.DocField) DocParam(com.google.copybara.doc.DocBase.DocParam)

Aggregations

Joiner (com.google.common.base.Joiner)2 DocExample (com.google.copybara.doc.DocBase.DocExample)2 DocField (com.google.copybara.doc.DocBase.DocField)2 DocFlag (com.google.copybara.doc.DocBase.DocFlag)2 DocFunction (com.google.copybara.doc.DocBase.DocFunction)2 DocModule (com.google.copybara.doc.DocBase.DocModule)2 DocParam (com.google.copybara.doc.DocBase.DocParam)2 Example (com.google.copybara.doc.annotations.Example)2 Arrays.stream (java.util.Arrays.stream)2 Collection (java.util.Collection)2 Parameter (com.beust.jcommander.Parameter)1 Ascii (com.google.common.base.Ascii)1 Preconditions (com.google.common.base.Preconditions)1 Splitter (com.google.common.base.Splitter)1 Strings (com.google.common.base.Strings)1 Strings.emptyToNull (com.google.common.base.Strings.emptyToNull)1 ImmutableList (com.google.common.collect.ImmutableList)1 ImmutableList.toImmutableList (com.google.common.collect.ImmutableList.toImmutableList)1 Lists (com.google.common.collect.Lists)1 HtmlEscapers (com.google.common.html.HtmlEscapers)1