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

Example 1 with SkylarkModuleDoc

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

the class SkylarkDocumentationTest method testSkylarkCallableOverriding.

@Test
public void testSkylarkCallableOverriding() throws Exception {
    Map<String, SkylarkModuleDoc> objects = collect(MockClassE.class);
    assertThat(objects).hasSize(1);
    assertThat(objects).containsKey("MockClassE");
    SkylarkModuleDoc moduleDoc = objects.get("MockClassE");
    assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassE");
    assertThat(moduleDoc.getMethods()).hasSize(1);
    SkylarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
    assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassA#get");
    assertThat(methodDoc.getSignature()).isEqualTo("<a class=\"anchor\" href=\"int.html\">int</a> MockClassE.get()");
}

Example 2 with SkylarkModuleDoc

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

the class SkylarkDocumentationTest method testSkylarkCallableParameters.

@Test
public void testSkylarkCallableParameters() throws Exception {
    Map<String, SkylarkModuleDoc> objects = collect(MockClassD.class);
    assertThat(objects).hasSize(1);
    assertThat(objects).containsKey("MockClassD");
    SkylarkModuleDoc moduleDoc = objects.get("MockClassD");
    assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassD");
    assertThat(moduleDoc.getMethods()).hasSize(1);
    SkylarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
    assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassD#test");
    assertThat(methodDoc.getSignature()).isEqualTo("<a class=\"anchor\" href=\"int.html\">int</a> " + "MockClassD.test(arg0:<a class=\"anchor\" href=\"int.html\">int</a>, " + "b, *, c, d=1)");
    assertThat(methodDoc.getParams()).hasSize(3);
}

Example 3 with SkylarkModuleDoc

use of com.google.devtools.build.docgen.skylark.SkylarkModuleDoc 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 4 with SkylarkModuleDoc

use of com.google.devtools.build.docgen.skylark.SkylarkModuleDoc 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 5 with SkylarkModuleDoc

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

the class SkylarkDocumentationCollector method collectJavaObjects.

/**
   * Collects and returns all the Java objects reachable in Skylark from (and including)
   * firstClass with the corresponding SkylarkModule annotation.
   *
   * <p>Note that the {@link SkylarkModule} annotation for firstClass - firstModule -
   * is also an input parameter, because some top level Skylark built-in objects and methods
   * are not annotated on the class, but on a field referencing them.
   */
@VisibleForTesting
static void collectJavaObjects(SkylarkModule firstModule, Class<?> firstClass, Map<String, SkylarkModuleDoc> modules) {
    Set<Class<?>> done = new HashSet<>();
    Deque<Class<?>> toProcess = new LinkedList<>();
    Map<Class<?>, SkylarkModule> annotations = new HashMap<>();
    toProcess.addLast(firstClass);
    annotations.put(firstClass, firstModule);
    while (!toProcess.isEmpty()) {
        Class<?> c = toProcess.removeFirst();
        SkylarkModule annotation = annotations.get(c);
        done.add(c);
        if (!modules.containsKey(annotation.name())) {
            modules.put(annotation.name(), new SkylarkModuleDoc(annotation, c));
        }
        SkylarkModuleDoc module = modules.get(annotation.name());
        if (module.javaMethodsNotCollected()) {
            ImmutableMap<Method, SkylarkCallable> methods = FuncallExpression.collectSkylarkMethodsWithAnnotation(c);
            for (Map.Entry<Method, SkylarkCallable> entry : methods.entrySet()) {
                module.addMethod(new SkylarkJavaMethodDoc(module, entry.getKey(), entry.getValue()));
            }
            for (Map.Entry<Method, SkylarkCallable> method : methods.entrySet()) {
                Class<?> returnClass = method.getKey().getReturnType();
                if (returnClass.isAnnotationPresent(SkylarkModule.class) && !done.contains(returnClass)) {
                    toProcess.addLast(returnClass);
                    annotations.put(returnClass, returnClass.getAnnotation(SkylarkModule.class));
                }
            }
        }
    }
}