Examples with SkylarkBuiltinMethodDoc com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc used on opensource projects

Example 1 with SkylarkBuiltinMethodDoc

use of com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc in project bazel by bazelbuild.

the class SkylarkDocumentationProcessor method getCommandLineAPIDoc.

/**
   * Returns the API doc for the specified Skylark object in a command line printable format,
   * params[0] identifies either a module or a top-level object, the optional params[1] identifies a
   * method in the module.<br>
   * Returns null if no Skylark object is found.
   */
public static String getCommandLineAPIDoc(String[] params) throws ClassPathException {
    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules();
    SkylarkModuleDoc toplevelModuleDoc = modules.get(SkylarkDocumentationCollector.getTopLevelModule().name());
    if (modules.containsKey(params[0])) {
        // Top level module
        SkylarkModuleDoc module = modules.get(params[0]);
        if (params.length == 1) {
            String moduleName = module.getAnnotation().name();
            StringBuilder sb = new StringBuilder();
            sb.append(moduleName).append("\n\t").append(module.getAnnotation().doc()).append("\n");
            // Print the signature of all built-in methods
            for (SkylarkBuiltinMethodDoc method : module.getBuiltinMethods().values()) {
                printBuiltinFunctionDoc(moduleName, method, sb);
            }
            // Print all Java methods
            for (SkylarkJavaMethodDoc method : module.getJavaMethods()) {
                printJavaFunctionDoc(method, sb);
            }
            return DocgenConsts.toCommandLineFormat(sb.toString());
        } else {
            return getFunctionDoc(module.getAnnotation().name(), params[1], module);
        }
    } else if (toplevelModuleDoc.getBuiltinMethods().containsKey(params[0])) {
        // Top level object / function
        return getFunctionDoc(null, params[0], toplevelModuleDoc);
    }
    return null;
}

Example 2 with SkylarkBuiltinMethodDoc

use of com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc in project bazel by bazelbuild.

the class SkylarkDocumentationCollector method collectBuiltinDoc.

private static void collectBuiltinDoc(Map<String, SkylarkModuleDoc> modules, Field[] fields) {
    for (Field field : fields) {
        if (field.isAnnotationPresent(SkylarkSignature.class)) {
            SkylarkSignature skylarkSignature = field.getAnnotation(SkylarkSignature.class);
            Class<?> moduleClass = skylarkSignature.objectType();
            SkylarkModule skylarkModule = moduleClass.equals(Object.class) ? getTopLevelModule() : Runtime.getCanonicalRepresentation(moduleClass).getAnnotation(SkylarkModule.class);
            if (skylarkModule == null) {
                // TODO(bazel-team): we currently have undocumented methods on undocumented data
                // structures, namely java.util.List. Remove this case when we are done.
                Preconditions.checkState(!skylarkSignature.documented());
                Preconditions.checkState(moduleClass == List.class);
            } else {
                if (!modules.containsKey(skylarkModule.name())) {
                    modules.put(skylarkModule.name(), new SkylarkModuleDoc(skylarkModule, moduleClass));
                }
                SkylarkModuleDoc module = modules.get(skylarkModule.name());
                module.addMethod(new SkylarkBuiltinMethodDoc(module, skylarkSignature, field.getType()));
            }
        }
    }
}

Example 3 with SkylarkBuiltinMethodDoc

use of com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc in project bazel by bazelbuild.

the class SkylarkDocumentationTest method checkSkylarkTopLevelEnvItemsAreDocumented.

@SuppressWarnings("unchecked")
private void checkSkylarkTopLevelEnvItemsAreDocumented(Environment env) throws Exception {
    Map<String, String> docMap = new HashMap<>();
    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules();
    SkylarkModuleDoc topLevel = modules.remove(SkylarkDocumentationCollector.getTopLevelModule().name());
    for (Entry<String, SkylarkBuiltinMethodDoc> entry : topLevel.getBuiltinMethods().entrySet()) {
        docMap.put(entry.getKey(), entry.getValue().getDocumentation());
    }
    for (Entry<String, SkylarkModuleDoc> entry : modules.entrySet()) {
        docMap.put(entry.getKey(), entry.getValue().getDocumentation());
    }
    List<String> undocumentedItems = new ArrayList<>();
    // All built in variables are registered in the Skylark global environment.
    for (String varname : env.getVariableNames()) {
        if (docMap.containsKey(varname)) {
            if (docMap.get(varname).isEmpty()) {
                undocumentedItems.add(varname);
            }
        } else {
            undocumentedItems.add(varname);
        }
    }
    assertWithMessage("Undocumented Skylark Environment items: " + undocumentedItems).that(undocumentedItems).isEmpty();
}

Example 4 with SkylarkBuiltinMethodDoc

use of com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc in project bazel by bazelbuild.

the class SkylarkDocumentationProcessor method getFunctionDoc.

private static String getFunctionDoc(String moduleName, String methodName, SkylarkModuleDoc module) {
    if (module.getBuiltinMethods().containsKey(methodName)) {
        // Create the doc for the built-in function
        SkylarkBuiltinMethodDoc method = module.getBuiltinMethods().get(methodName);
        StringBuilder sb = new StringBuilder();
        printBuiltinFunctionDoc(moduleName, method, sb);
        sb.append(method.getParams());
        return DocgenConsts.removeDuplicatedNewLines(DocgenConsts.toCommandLineFormat(sb.toString()));
    } else {
        // Search if there are matching Java functions
        StringBuilder sb = new StringBuilder();
        boolean foundMatchingMethod = false;
        for (SkylarkJavaMethodDoc method : module.getJavaMethods()) {
            if (method.getName().equals(methodName)) {
                printJavaFunctionDoc(method, sb);
                foundMatchingMethod = true;
            }
        }
        if (foundMatchingMethod) {
            return DocgenConsts.toCommandLineFormat(sb.toString());
        }
    }
    return null;
}