Enhanced javadoc of Asciidoctor.Factory.create(Classloader) to hint on OSGi
@@ -811,26 +811,36 @@ public interface Asciidoctor {
}
/**
- * Creates a new instance of Asciidoctor and sets a specific classloader for the JRuby runtime to use. This method is mostly
- * used in environments where different threads may have different classloaders, like build tools sbt or ANT.
+ * Creates a new instance of Asciidoctor and sets a specific classloader for the JRuby runtime to use.
+ * This method is for use in environments like OSGi.
+ * To initialize Asciidoctor in OSGi create the Asciidoctor instance like this:
+ *
+ * <pre>
+ * org.jruby.javasupport.JavaEmbedUtils.initialize(Arrays.asList("uri:classloader:/gems/asciidoctor-1.5.8/lib"));
+ * Asciidoctor asciidoctor = Asciidoctor.Factory.create(this.getClass().getClassLoader()); <3>
+ * </pre>
*
* @param classloader
* @return Asciidoctor instance which uses JRuby to wraps Asciidoctor
* Ruby calls.
- * @deprecated Please use {@link #create()} and set the TCCL before or {@link #create(List)} passing the paths
- * that you would have used to create the ClassLoader.
*/
public static Asciidoctor create(ClassLoader classloader) {
return JRubyAsciidoctor.create(classloader);
}
/**
- * Cerates a new instance of Asciidoctor and sets a specific classloader and gempath for the JRuby runtime to use.
+ * Creates a new instance of Asciidoctor and sets a specific classloader and gempath for the JRuby runtime to use.
+ * This method is for use in environments like OSGi.
+ * To initialize Asciidoctor in OSGi create the Asciidoctor instance like this:
+ *
+ * <pre>
+ * org.jruby.javasupport.JavaEmbedUtils.initialize(Arrays.asList("uri:classloader:/gems/asciidoctor-1.5.8/lib"));
+ * Asciidoctor asciidoctor = Asciidoctor.Factory.create(this.getClass().getClassLoader()); <3>
+ * </pre>
+ *
* @param classloader
* @param gemPath
* @return Asciidoctor instance which uses JRuby to wraps Asciidoctor
- * @deprecated Please use {@link #create(String)} and set the TCCL before or {@link #create(List, String)}
- * passing the paths that you would have used to create the ClassLoader.
*/
public static Asciidoctor create(ClassLoader classloader, String gemPath) {
return JRubyAsciidoctor.create(classloader, gemPath);
