From c9c5c66eb629fe9a0c0697d10a9293476dfe19d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Florian=20N=C3=BCcke?= <florian@nuecke.de>
Date: Tue, 7 Oct 2014 17:53:45 +0200
Subject: [PATCH] Alternative docstring pattern and added note to
 documentation.

---
 src/main/java/li/cil/oc/api/machine/Callback.java | 8 ++++++++
 src/main/scala/li/cil/oc/util/mods/NEI.scala      | 7 +++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/main/java/li/cil/oc/api/machine/Callback.java b/src/main/java/li/cil/oc/api/machine/Callback.java
index 64bf4858b..45781d145 100644
--- a/src/main/java/li/cil/oc/api/machine/Callback.java
+++ b/src/main/java/li/cil/oc/api/machine/Callback.java
@@ -88,6 +88,14 @@ public @interface Callback {
      * more importantly you should document the expected parameters and return
      * type here.
      * <p/>
+     * <em>Important</em>: the recommended format is either<br/>
+     * <tt>function(arg:type[, optionArg:type]):resultType -- Description.</tt><br/>
+     * or<br/>
+     * <tt>function(arg:type[, optionArg:type]):resultType; Description.</tt><br/>
+     * where the argument list can be of any format (as long as it doesn't contain
+     * further braces), and the return type is optional. These two formats are
+     * recognized by OC's NEI component documentation plugin. If you use a
+     * different format, the doc string will be used as-is.
      */
     String doc() default "";
 
diff --git a/src/main/scala/li/cil/oc/util/mods/NEI.scala b/src/main/scala/li/cil/oc/util/mods/NEI.scala
index 963a3784d..b78d9d05e 100644
--- a/src/main/scala/li/cil/oc/util/mods/NEI.scala
+++ b/src/main/scala/li/cil/oc/util/mods/NEI.scala
@@ -55,6 +55,8 @@ class DocumentationHandler(val pages: Option[Array[String]]) extends IUsageHandl
 
   private val DocPattern = """^function(\([^)]*\)[^-]*) -- (.*)$""".r
 
+  private val VexPattern = """^function(\([^)]*\)[^-]*); (.*)$""".r
+
   private def wrap(line: String, width: Int) = GuiDraw.fontRenderer.listFormattedStringToWidth(line, width)
 
   override def getUsageHandler(input: String, ingredients: AnyRef*): IUsageHandler = {
@@ -67,8 +69,9 @@ class DocumentationHandler(val pages: Option[Array[String]]) extends IUsageHandl
                 val doc = callback.annotation.doc
                 if (Strings.isNullOrEmpty(doc)) name
                 else {
-                  val (signature, documentation) = DocPattern findFirstIn doc match {
-                    case Some(DocPattern(head, tail)) => (name + head, tail)
+                  val (signature, documentation) = doc match {
+                    case DocPattern(head, tail) => (name + head, tail)
+                    case VexPattern(head, tail) => (name + head, tail)
                     case _ => (name, doc)
                   }
                   wrap(signature, 160).map(EnumChatFormatting.BLACK.toString + _).mkString("\n") +