Follow naming convention for parameter names in method docstrings (#352)

* Update parameter names in documentation Because parameter names may not be written in the same format between C++, Objective-C, and Java, it is impossible to have doxygen- or javadoc-style @param annotations that match for all languages. This change simply looks for "@param <PARAMNAME>" in the docstring and rewrites it the same way as the sourcecode does. * Replace all occurrences of parameter name in docstring * Also update Java for static methods * Add multi-word parameter name to test suite And reference it from the docstring. * Revert "Add multi-word parameter name to test suite" This reverts commit 785a226. * Add multi-word parameter name to test suite And reference it from the docstring.
dropbox · Feb 22, 2018 · 0001a3e · 0001a3e · WoodyGuo · May 14, 2018
1 parent 565425d
commit 0001a3e
Show file tree

Hide file tree

Showing 8 changed files with 32 additions and 4 deletions.
diff --git a/src/source/CppGenerator.scala b/src/source/CppGenerator.scala
@@ -309,7 +309,7 @@ class CppGenerator(spec: Spec) extends Generator(spec) {
         // Methods
         for (m <- i.methods) {
           w.wl
-          writeDoc(w, m.doc)
+          writeMethodDoc(w, m, idCpp.local)
           val ret = marshal.returnType(m.ret, methodNamesInScope)
           val params = m.params.map(p => marshal.paramType(p.ty, methodNamesInScope) + " " + idCpp.local(p.ident))
           if (m.static) {

diff --git a/src/source/JavaGenerator.scala b/src/source/JavaGenerator.scala
@@ -147,7 +147,7 @@ class JavaGenerator(spec: Spec) extends Generator(spec) {
         val throwException = spec.javaCppException.fold("")(" throws " + _)
         for (m <- i.methods if !m.static) {
           skipFirst { w.wl }
-          writeDoc(w, m.doc)
+          writeMethodDoc(w, m, idJava.local)
           val ret = marshal.returnType(m.ret)
           val params = m.params.map(p => {
             val nullityAnnotation = marshal.nullityAnnotation(p.ty).map(_ + " ").getOrElse("")
@@ -158,7 +158,7 @@ class JavaGenerator(spec: Spec) extends Generator(spec) {
         }
         for (m <- i.methods if m.static) {
           skipFirst { w.wl }
-          writeDoc(w, m.doc)
+          writeMethodDoc(w, m, idJava.local)
           val ret = marshal.returnType(m.ret)
           val params = m.params.map(p => {
             val nullityAnnotation = marshal.nullityAnnotation(p.ty).map(_ + " ").getOrElse("")

diff --git a/src/source/ObjcGenerator.scala b/src/source/ObjcGenerator.scala
@@ -107,7 +107,7 @@ class ObjcGenerator(spec: Spec) extends BaseObjcGenerator(spec) {
       if (i.ext.objc) w.wl(s"@protocol $self") else w.wl(s"@interface $self : NSObject")
       for (m <- i.methods) {
         w.wl
-        writeDoc(w, m.doc)
+        writeMethodDoc(w, m, idObjc.local)
         writeObjcFuncDecl(m, w)
         w.wl(";")
       }

diff --git a/src/source/generator.scala b/src/source/generator.scala
@@ -24,6 +24,7 @@ import djinni.syntax.Error
 import djinni.writer.IndentWriter
 import scala.language.implicitConversions
 import scala.collection.mutable
+import scala.util.matching.Regex
 
 package object generatorTools {
 
@@ -416,6 +417,15 @@ abstract class Generator(spec: Spec)
 
   // --------------------------------------------------------------------------
 
+  def writeMethodDoc(w: IndentWriter, method: Interface.Method, ident: IdentConverter) {
+    val paramReplacements = method.params.map(p => (s"\\b${Regex.quote(p.ident.name)}\\b", s"${ident(p.ident.name)}"))
+    val newDoc = Doc(method.doc.lines.map(l => {
+      paramReplacements.foldLeft(l)((line, rep) =>
+        line.replaceAll(rep._1, rep._2))
+    }))
+    writeDoc(w, newDoc)
+  }
+
   def writeDoc(w: IndentWriter, doc: Doc) {
     doc.lines.length match {
       case 0 =>

diff --git a/test-suite/djinni/varnames.djinni b/test-suite/djinni/varnames.djinni
@@ -6,6 +6,9 @@ _varname_record_ = record {
 }
 
 _varname_interface_ = interface +c {
+    # We should also rewrite parameter names in docstrings.
+    # _r_arg_ should be rewritten.
+    # _i_arg_ should not.
     _rmethod_(_r_arg_: _varname_record_): _varname_record_;
     _imethod_(_i_arg_: _varname_interface_): _varname_interface_;
 }
diff --git a/test-suite/generated-src/cpp/_varname_interface_.hpp b/test-suite/generated-src/cpp/_varname_interface_.hpp
@@ -13,6 +13,11 @@ class VarnameInterface {
 public:
     virtual ~VarnameInterface() {}
 
+    /**
+     * We should also rewrite parameter names in docstrings.
+     * _r_arg_ should be rewritten.
+     * _i_arg_ should not.
+     */
     virtual VarnameRecord _rmethod_(const VarnameRecord & _r_arg_) = 0;
 
     virtual std::shared_ptr<VarnameInterface> _imethod_(const std::shared_ptr<VarnameInterface> & _i_arg_) = 0;

diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/VarnameInterface.java b/test-suite/generated-src/java/com/dropbox/djinni/test/VarnameInterface.java
@@ -8,6 +8,11 @@
 import javax.annotation.Nonnull;
 
 public abstract class VarnameInterface {
+    /**
+     * We should also rewrite parameter names in docstrings.
+     * RArg should be rewritten.
+     * _i_arg_ should not.
+     */
     @Nonnull
     public abstract VarnameRecord Rmethod(@Nonnull VarnameRecord RArg);
 

diff --git a/test-suite/generated-src/objc/DBVarnameInterface.h b/test-suite/generated-src/objc/DBVarnameInterface.h
@@ -8,6 +8,11 @@
 
 @interface DBVarnameInterface : NSObject
 
+/**
+ * We should also rewrite parameter names in docstrings.
+ * RArg should be rewritten.
+ * _i_arg_ should not.
+ */
 - (nonnull DBVarnameRecord *)Rmethod:(nonnull DBVarnameRecord *)RArg;
 
 - (nullable DBVarnameInterface *)Imethod:(nullable DBVarnameInterface *)IArg;