Filling in some more javadoc.

fnuecke · fnuecke · commit a8d07183c199 · 2015-04-10T00:31:21.000+02:00
diff --git a/src/main/java/li/cil/oc/api/Manual.java b/src/main/java/li/cil/oc/api/Manual.java
@@ -71,7 +71,8 @@ public static void addProvider(ContentProvider provider) {
      * the image URL, i.e. <tt>![tooltip](prefix:data)</tt> will select the
      * image provider registered for the prefix <tt>prefix</tt>, and pass to
      * it the argument <tt>data</tt>, then use the returned renderer to draw
-     * an element in the place of the tag.
+     * an element in the place of the tag. The provided prefix is expected to
+     * be <em>without</em> the colon (<tt>:</tt>).
      * <p/>
      * Custom providers are only selected if a prefix is matched, otherwise
      * it'll treat it as a relative path to an image to load via Minecraft's
diff --git a/src/main/java/li/cil/oc/api/manual/ImageProvider.java b/src/main/java/li/cil/oc/api/manual/ImageProvider.java
@@ -1,8 +1,28 @@
 package li.cil.oc.api.manual;
 
 /**
- * Created by fnuecke on 4/9/2015.
+ * This allows implementing custom image providers for rendering custom content
+ * in manual pages. Each provider can be registered for one or more prefixes,
+ * and will be selected based on the prefix it was registered with. It is
+ * expected to return an image renderer, which essentially represents the
+ * area it will render to.
  */
 public interface ImageProvider {
-    ImageRenderer getImage(String href);
+    /**
+     * Gets an image renderer for the specified data.
+     * <p/>
+     * The data passed here will be part of the image URL following the prefix
+     * that the provider was registered with. So for example, if the provider
+     * was registered for the prefix <tt>custom</tt>, and the image to be
+     * rendered in the Markdown document was <tt>[blah](custom:the data]</tt>,
+     * then the string passed where would be <tt>the data</tt>.
+     * <p/>
+     * If there is no appropriate image renderer (for example, for the built-in
+     * item stack renderers: if the item definition is invalid), this should
+     * return <tt>null</tt>, it should <em>never</em> throw an exception.
+     *
+     * @param data the data part of the image definition.
+     * @return the image renderer for the data.
+     */
+    ImageRenderer getImage(String data);
 }
diff --git a/src/main/java/li/cil/oc/api/manual/ImageRenderer.java b/src/main/java/li/cil/oc/api/manual/ImageRenderer.java
@@ -1,12 +1,45 @@
 package li.cil.oc.api.manual;
 
 /**
- * Created by fnuecke on 4/9/2015.
+ * This allows implementing custom image renderers.
+ * <p/>
+ * Image renderers are used to draw custom areas in a manual page, defined as
+ * an image with a special URL, matching the prefix of a registered image
+ * provider. A renderer will then be used to draw something at the position
+ * of the image tag.
+ * <p/>
+ * Built-in image renderers are <tt>item</tt>, <tt>block</tt>, <tt>oredict</tt>
+ * and <tt>recipe</tt>.
  */
 public interface ImageRenderer {
+    /**
+     * The width of the area this renderer uses.
+     * <p/>
+     * This is used to offset the OpenGL state properly before calling
+     * {@link #render(int)}, as well as to know where to resume rendering
+     * other content below the image.
+     *
+     * @return the width of the rendered image.
+     */
     int getWidth();
 
+    /**
+     * The height of the area this renderer uses.
+     * <p/>
+     * This is used to compute the
+     *
+     * @return the height of the rendered image.
+     */
     int getHeight();
 
+    /**
+     * Render the image, with specified maximum width.
+     * <p/>
+     * This should render the image as is, the OpenGL state will be set up
+     * such that you can start drawing at (0,0,*), and render up to
+     * (getWidth,getHeight,*).
+     *
+     * @param maxWidth the maximum width usable for rendering.
+     */
     void render(int maxWidth);
 }
diff --git a/src/main/scala/li/cil/oc/util/PseudoMarkdown.scala b/src/main/scala/li/cil/oc/util/PseudoMarkdown.scala
@@ -492,9 +492,9 @@ object PseudoMarkdown {
   }
 
   object ItemRenderProvider extends ImageProvider {
-    override def getImage(href: String): ImageRenderer = {
-      val splitIndex = href.lastIndexOf('@')
-      val (name, optMeta) = if (splitIndex > 0) href.splitAt(splitIndex) else (href, "")
+    override def getImage(data: String): ImageRenderer = {
+      val splitIndex = data.lastIndexOf('@')
+      val (name, optMeta) = if (splitIndex > 0) data.splitAt(splitIndex) else (data, "")
       val meta = if (Strings.isNullOrEmpty(optMeta)) 0 else Integer.parseInt(optMeta.drop(1))
       Item.itemRegistry.getObject(name) match {
         case item: Item => new ItemStackRenderer(Array(new ItemStack(item, 1, meta)))
@@ -504,9 +504,9 @@ object PseudoMarkdown {
   }
 
   object BlockRenderProvider extends ImageProvider {
-    override def getImage(href: String): ImageRenderer = {
-      val splitIndex = href.lastIndexOf('@')
-      val (name, optMeta) = if (splitIndex > 0) href.splitAt(splitIndex) else (href, "")
+    override def getImage(data: String): ImageRenderer = {
+      val splitIndex = data.lastIndexOf('@')
+      val (name, optMeta) = if (splitIndex > 0) data.splitAt(splitIndex) else (data, "")
       val meta = if (Strings.isNullOrEmpty(optMeta)) 0 else Integer.parseInt(optMeta.drop(1))
       Block.blockRegistry.getObject(name) match {
         case block: Block => new ItemStackRenderer(Array(new ItemStack(block, 1, meta)))
@@ -516,8 +516,8 @@ object PseudoMarkdown {
   }
 
   object OreDictRenderProvider extends ImageProvider {
-    override def getImage(desc: String): ImageRenderer = {
-      val stacks = OreDictionary.getOres(desc)
+    override def getImage(data: String): ImageRenderer = {
+      val stacks = OreDictionary.getOres(data)
       if (stacks != null && stacks.nonEmpty) new ItemStackRenderer(stacks.toArray(new Array[ItemStack](stacks.size())))
       else null
     }
