Commit 0001a3e8 authored by Louis Wilson's avatar Louis Wilson Committed by Xianwen Chen

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 785a22690ff14261fc7c4843984d467784956a47.

* Add multi-word parameter name to test suite

And reference it from the docstring.
parent 565425de
......@@ -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) {
......
......@@ -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("")
......
......@@ -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(";")
}
......
......@@ -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 =>
......
......@@ -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_;
}
......@@ -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;
......
......@@ -8,6 +8,11 @@ import javax.annotation.CheckForNull;
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);
......
......@@ -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;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment