Skip to content

Commit

Permalink
[docs] Remove hidden features from the API documentation.
Browse files Browse the repository at this point in the history 
Doclet is rewrote in order to hide the hidden features from the SARL
language. The default values of the formal parameters are also output.

Signed-off-by: Stéphane Galland <galland@arakhne.org>
  • Loading branch information
@gallandarakhneorg
gallandarakhneorg committed Oct 5, 2017
1 parent 0bba7d8 commit 0e77e4a
Show file tree
Hide file tree
Showing 28 changed files with 3,639 additions and 163 deletions.
4 changes: 4 additions & 0 deletions build-tools/scripts/generate-aggregate-javadoc.sh
View file
@@ -1,7 +1,11 @@
#!/usr/bin/env bash

# With Janus
PLUGIN_MODULES=("./main/coreplugins/io.sarl.lang.core" "./main/apiplugins/io.sarl.core" "./main/apiplugins/io.sarl.util" "./sre/io.janusproject/io.janusproject.plugin")

# Without Janus
#PLUGIN_MODULES=("./main/coreplugins/io.sarl.lang.core" "./main/apiplugins/io.sarl.core" "./main/apiplugins/io.sarl.util")

SOURCE_PATH=""
for module in "${PLUGIN_MODULES[@]}"
do
Expand Down
44 changes: 0 additions & 44 deletions docs/io.sarl.docs.doclet/src/main/java/io/sarl/docs/doclet/ProxyInstaller.java
View file

This file was deleted.

41 changes: 40 additions & 1 deletion docs/io.sarl.docs.doclet/src/main/java/io/sarl/docs/doclet/SarlConfiguration.java
View file
Expand Up @@ -21,11 +21,27 @@

package io.sarl.docs.doclet;

import java.util.Set;
import java.util.TreeSet;

import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.PackageDoc;
import com.sun.tools.doclets.formats.html.ConfigurationImpl;
import com.sun.tools.doclets.formats.html.HtmlDocletWriter;
import com.sun.tools.doclets.internal.toolkit.WriterFactory;
import com.sun.tools.doclets.internal.toolkit.util.links.LinkFactory;

import io.sarl.docs.doclet.exclude.ApidocExcluder;
import io.sarl.docs.doclet.exclude.DefaultApidocExcluder;
import io.sarl.docs.doclet.proxy.ProgrammaticWrappingProxyInstaller;
import io.sarl.docs.doclet.proxy.ProxyInstaller;
import io.sarl.docs.doclet.references.SarlLinkFactory;
import io.sarl.docs.doclet.utils.Reflect;
import io.sarl.docs.doclet.utils.SARLFeatureAccess;
import io.sarl.docs.doclet.utils.SarlMessageRetreiver;
import io.sarl.docs.doclet.utils.Utils;
import io.sarl.docs.doclet.writers.SarlWriterFactory;

/** Configuration for the SARL doclet.
*
* @author $Author: sgalland$
Expand Down Expand Up @@ -82,9 +98,32 @@ public ApidocExcluder getApidocExcluder() {
*/
public ProxyInstaller getProxyInstaller() {
if (this.proxyInstaller == null) {
this.proxyInstaller = new NoProxyInstaller(this);
this.proxyInstaller = new ProgrammaticWrappingProxyInstaller(this);
}
return this.proxyInstaller;
}

@Override
public void setOptions() throws Fault {
super.setOptions();
resetPackageList();
}

/** Reset the list of packages for avoiding duplicates.
*
* <p>The inherited implementation uses a HashSet that allow
* the same package to be stored multiple times. Here,
* we uses a TreeSet for using the "compareTo" mechanism.
*/
private void resetPackageList() {
final Set<PackageDoc> set = new TreeSet<>();
for (final PackageDoc pack : this.root.specifiedPackages()) {
set.add(pack);
}
for (final ClassDoc clazz : this.root.specifiedClasses()) {
set.add(clazz.containingPackage());
}
this.packages = Utils.toArray(this.packages, set);
}

}
43 changes: 34 additions & 9 deletions docs/io.sarl.docs.doclet/src/main/java/io/sarl/docs/doclet/SarlDoclet.java
View file
Expand Up @@ -57,6 +57,10 @@
import com.sun.tools.doclets.internal.toolkit.util.Util;
import com.sun.tools.javac.jvm.Profile;

import io.sarl.docs.doclet.proxy.ProxyInstaller;
import io.sarl.docs.doclet.utils.Reflect;
import io.sarl.docs.doclet.utils.Utils;

/** SARL Doclet.
*
* @author $Author: sgalland$
Expand Down Expand Up @@ -131,12 +135,12 @@ protected boolean isValidDoclet(AbstractDoclet doclet) {
@SuppressWarnings("checkstyle:all")
@Override
public boolean start(AbstractDoclet doclet, RootDoc root) {
configuration().root = configuration().getProxyInstaller().processDocument(root);
configuration().root = configuration().getProxyInstaller().installProxies(root);
if (!isValidDoclet(doclet)) {
return false;
}
try {
Reflect.call(this, AbstractDoclet.class, "startGeneration", //$NON-NLS-1$
Reflect.callProc(this, AbstractDoclet.class, "startGeneration", //$NON-NLS-1$
new Class[] { RootDoc.class },
configuration().root);
} catch (DocletAbortException e) {
Expand All @@ -154,6 +158,19 @@ public boolean start(AbstractDoclet doclet, RootDoc root) {
return true;
}

private AnnotationTypeDoc asAnnotationTypeDoc(ClassDoc doc) {
final ProxyInstaller proxyInstaller = configuration().getProxyInstaller();
final ClassDoc current = proxyInstaller.unwrap(doc);
AnnotationTypeDoc annotationTypeDoc = null;
if (current instanceof AnnotationTypeDoc) {
annotationTypeDoc = (AnnotationTypeDoc) current;
}
if (annotationTypeDoc == null) {
annotationTypeDoc = current.asAnnotationTypeDoc();
}
return proxyInstaller.wrap(annotationTypeDoc);
}

@Override
protected void generateClassFiles(ClassDoc[] classes, ClassTree classtree) {
Arrays.sort(classes);
Expand All @@ -165,9 +182,11 @@ protected void generateClassFiles(ClassDoc[] classes, ClassTree classtree) {
final ClassDoc previous = i == 0 ? null : classes[i - 1];
final ClassDoc next = (i + 1) == classes.length ? null : classes[i + 1];
try {
if (current.isAnnotationType()) {
final AnnotationTypeDoc annotationTypeDoc =
current.isAnnotationType() ? asAnnotationTypeDoc(current) : null;
if (annotationTypeDoc != null) {
final AbstractBuilder annotationTypeBuilder = configuration().getBuilderFactory()
.getAnnotationTypeBuilder((AnnotationTypeDoc) current, previous, next);
.getAnnotationTypeBuilder(annotationTypeDoc, previous, next);
annotationTypeBuilder.build();
} else {
final AbstractBuilder classBuilder = configuration().getBuilderFactory()
Expand All @@ -188,8 +207,8 @@ protected void generateClassFiles(ClassDoc[] classes, ClassTree classtree) {
protected void generatePackageFiles(ClassTree classtree) throws Exception {
final PackageDoc[] packages = configuration().packages;
if (packages.length > 1) {
PackageIndexFrameWriter.generate(configuration());
}
PackageIndexFrameWriter.generate(configuration());
}
PackageDoc prev = null;
PackageDoc next;
for (int i = 0; i < packages.length; i++) {
Expand Down Expand Up @@ -239,8 +258,12 @@ protected void generateProfileFiles() throws Exception {
// and profilename-package-frame.html pages for that package.
if (!(configuration().nodeprecated && Util.isDeprecated(packages[j]))) {
ProfilePackageFrameWriter.generate(configuration(), packages[j], i);
next = (j + 1 < packages.length)
&& (packages[j + 1].name().length() > 0) ? packages[j + 1] : null;
if ((j + 1 < packages.length)
&& (packages[j + 1].name().length() > 0)) {
next = packages[j + 1];
} else {
next = null;
}
final AbstractBuilder profilePackageSummaryBuilder = configuration()
.getBuilderFactory().getProfilePackageSummaryBuilder(
packages[j], prev, next, Profile.lookup(i));
Expand Down Expand Up @@ -292,7 +315,9 @@ protected void generateOtherFiles(RootDoc root, ClassTree classtree) throws Exce
}

if (!(configuration().nodeprecatedlist || nodeprecated)) {
DeprecatedListWriter.generate(configuration());
configuration().getProxyInstaller().noProxy(configuration(), () -> {
DeprecatedListWriter.generate(configuration());
});
}

AllClassesFrameWriter.generate(configuration(),
Expand Down
8 changes: 6 additions & 2 deletions docs/io.sarl.docs.doclet/src/main/java/io/sarl/docs/doclet/SarlDocletTester.java
View file
Expand Up @@ -23,6 +23,8 @@

import com.sun.tools.javadoc.Main;

import io.sarl.docs.doclet.utils.Utils;

/** Tester for the SARL Doclet.
*
* @author $Author: sgalland$
Expand All @@ -41,6 +43,7 @@ private SarlDocletTester() {
*
* @param args arguments.
*/
@SuppressWarnings("checkstyle:all")
public static void main(String[] args) {
try {
System.setProperty("http.proxyHost", "proxy.utbm.fr"); //$NON-NLS-1$ //$NON-NLS-2$
Expand All @@ -49,8 +52,9 @@ public static void main(String[] args) {
"-private", //$NON-NLS-1$
"-source", "1.8", //$NON-NLS-1$ //$NON-NLS-2$
"-doclet", SarlDoclet.class.getName(), //$NON-NLS-1$
//"-sourcepath", "/home/sgalland/git/sarl/main/coreplugins/io.sarl.lang.core/src", //$NON-NLS-1$ //$NON-NLS-2$
"-sourcepath", "/home/sgalland/git/sarl/main/apiplugins/io.sarl.core/src-gen", //$NON-NLS-1$ //$NON-NLS-2$
"-sourcepath", "/home/sgalland/git/sarl/main/coreplugins/io.sarl.lang.core/src", //$NON-NLS-1$ //$NON-NLS-2$
//"-sourcepath", "/home/sgalland/git/sarl/main/apiplugins/io.sarl.core/src-gen", //$NON-NLS-1$ //$NON-NLS-2$
//"-sourcepath", "/home/sgalland/git/sarl/main/coreplugins/io.sarl.lang.core/src:/home/sgalland/git/sarl/main/apiplugins/io.sarl.core/src-gen", //$NON-NLS-1$ //$NON-NLS-2$
"-d", "/home/sgalland/tmp/gen-site", //$NON-NLS-1$ //$NON-NLS-2$
"-subpackages", "io", //$NON-NLS-1$ //$NON-NLS-2$
"-link", "http://docs.oracle.com/javase/8/docs/api/", //$NON-NLS-1$ //$NON-NLS-2$
Expand Down
2 changes: 1 addition & 1 deletion ...a/io/sarl/docs/doclet/ApidocExcluder.java → ...l/docs/doclet/exclude/ApidocExcluder.java
View file
Expand Up @@ -19,7 +19,7 @@
* limitations under the License.
*/

package io.sarl.docs.doclet;
package io.sarl.docs.doclet.exclude;

import com.sun.javadoc.Doc;

Expand Down
4 changes: 3 additions & 1 deletion ...rl/docs/doclet/DefaultApidocExcluder.java → ...doclet/exclude/DefaultApidocExcluder.java
View file
Expand Up @@ -19,11 +19,13 @@
* limitations under the License.
*/

package io.sarl.docs.doclet;
package io.sarl.docs.doclet.exclude;

import com.sun.javadoc.Doc;
import com.sun.javadoc.ProgramElementDoc;

import io.sarl.docs.doclet.utils.Utils;

/** Check if an element should be ignored into the API doc.
*
* @author $Author: sgalland$
Expand Down
36 changes: 25 additions & 11 deletions ...o/sarl/docs/doclet/JreProxyInstaller.java → .../docs/doclet/proxy/JreProxyInstaller.java
View file
Expand Up @@ -19,7 +19,7 @@
* limitations under the License.
*/

package io.sarl.docs.doclet;
package io.sarl.docs.doclet.proxy;

import java.lang.ref.WeakReference;
import java.lang.reflect.Array;
Expand All @@ -33,10 +33,14 @@
import java.util.List;
import java.util.Set;

import com.sun.javadoc.AnnotationTypeDoc;
import com.sun.javadoc.Doc;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.RootDoc;

import io.sarl.docs.doclet.SarlConfiguration;
import io.sarl.docs.doclet.exclude.ApidocExcluder;

/** Install the proxies for the {@code Doc}.
* This object is filtering the arrays that are replied functions in {@link RootDoc} or {@link ProgramElementDoc}.
*
Expand Down Expand Up @@ -73,11 +77,20 @@ public JreProxyInstaller(SarlConfiguration configuration) {
}

@Override
public RootDoc processDocument(RootDoc obj) {
//return obj;
public RootDoc installProxies(RootDoc obj) {
return (RootDoc) processElement(obj, null);
}

@Override
public void installProxies(SarlConfiguration configuration) {
configuration.root = (RootDoc) processElement(configuration.root, null);
}

@Override
public void uninstallProxies(SarlConfiguration configuration) {
configuration.root = unwrap(configuration.root);
}

/** Filter the given document.
*
* @param obj the document to filter.
Expand Down Expand Up @@ -120,6 +133,11 @@ protected Object processElement(Object obj, Class<?> expectedType) {
return obj;
}

@Override
public AnnotationTypeDoc wrap(AnnotationTypeDoc obj) {
return (AnnotationTypeDoc) wrap((Object) obj);
}

/** Unwrap the given object.
*
* @param object the object.
Expand All @@ -133,15 +151,11 @@ protected Object wrap(Object object) {
return Proxy.newProxyInstance(type.getClassLoader(), type.getInterfaces(), new ProxyHandler(object));
}

/** Unwrap the given object.
*
* @param proxy the object.
* @return the unwrapped object.
*/
@SuppressWarnings({ "static-method", "synthetic-access" })
protected Object unwrap(Object proxy) {
@SuppressWarnings({ "synthetic-access", "unchecked" })
@Override
public <T> T unwrap(T proxy) {
if (proxy != null && Proxy.isProxyClass(proxy.getClass())) {
return ((ProxyHandler) Proxy.getInvocationHandler(proxy)).target;
return (T) ((ProxyHandler) Proxy.getInvocationHandler(proxy)).target;
}
return proxy;
}
Expand Down
27 changes: 25 additions & 2 deletions ...io/sarl/docs/doclet/NoProxyInstaller.java → ...l/docs/doclet/proxy/NoProxyInstaller.java
View file
Expand Up @@ -19,10 +19,13 @@
* limitations under the License.
*/

package io.sarl.docs.doclet;
package io.sarl.docs.doclet.proxy;

import com.sun.javadoc.AnnotationTypeDoc;
import com.sun.javadoc.RootDoc;

import io.sarl.docs.doclet.SarlConfiguration;

/** Install the proxies for the {@code Doc}.
*
* @author $Author: sgalland$
Expand All @@ -42,7 +45,27 @@ public NoProxyInstaller(SarlConfiguration configuration) {
}

@Override
public RootDoc processDocument(RootDoc obj) {
public RootDoc installProxies(RootDoc obj) {
return obj;
}

@Override
public void installProxies(SarlConfiguration configuration) {
//
}

@Override
public void uninstallProxies(SarlConfiguration configuration) {
//
}

@Override
public <T> T unwrap(T obj) {
return obj;
}

@Override
public AnnotationTypeDoc wrap(AnnotationTypeDoc obj) {
return obj;
}

Expand Down

0 comments on commit 0e77e4a

Please sign in to comment.