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) { ...@@ -309,7 +309,7 @@ class CppGenerator(spec: Spec) extends Generator(spec) {
// Methods // Methods
for (m <- i.methods) { for (m <- i.methods) {
w.wl w.wl
writeDoc(w, m.doc) writeMethodDoc(w, m, idCpp.local)
val ret = marshal.returnType(m.ret, methodNamesInScope) val ret = marshal.returnType(m.ret, methodNamesInScope)
val params = m.params.map(p => marshal.paramType(p.ty, methodNamesInScope) + " " + idCpp.local(p.ident)) val params = m.params.map(p => marshal.paramType(p.ty, methodNamesInScope) + " " + idCpp.local(p.ident))
if (m.static) { if (m.static) {
......
...@@ -147,7 +147,7 @@ class JavaGenerator(spec: Spec) extends Generator(spec) { ...@@ -147,7 +147,7 @@ class JavaGenerator(spec: Spec) extends Generator(spec) {
val throwException = spec.javaCppException.fold("")(" throws " + _) val throwException = spec.javaCppException.fold("")(" throws " + _)
for (m <- i.methods if !m.static) { for (m <- i.methods if !m.static) {
skipFirst { w.wl } skipFirst { w.wl }
writeDoc(w, m.doc) writeMethodDoc(w, m, idJava.local)
val ret = marshal.returnType(m.ret) val ret = marshal.returnType(m.ret)
val params = m.params.map(p => { val params = m.params.map(p => {
val nullityAnnotation = marshal.nullityAnnotation(p.ty).map(_ + " ").getOrElse("") val nullityAnnotation = marshal.nullityAnnotation(p.ty).map(_ + " ").getOrElse("")
...@@ -158,7 +158,7 @@ class JavaGenerator(spec: Spec) extends Generator(spec) { ...@@ -158,7 +158,7 @@ class JavaGenerator(spec: Spec) extends Generator(spec) {
} }
for (m <- i.methods if m.static) { for (m <- i.methods if m.static) {
skipFirst { w.wl } skipFirst { w.wl }
writeDoc(w, m.doc) writeMethodDoc(w, m, idJava.local)
val ret = marshal.returnType(m.ret) val ret = marshal.returnType(m.ret)
val params = m.params.map(p => { val params = m.params.map(p => {
val nullityAnnotation = marshal.nullityAnnotation(p.ty).map(_ + " ").getOrElse("") val nullityAnnotation = marshal.nullityAnnotation(p.ty).map(_ + " ").getOrElse("")
......
...@@ -107,7 +107,7 @@ class ObjcGenerator(spec: Spec) extends BaseObjcGenerator(spec) { ...@@ -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") if (i.ext.objc) w.wl(s"@protocol $self") else w.wl(s"@interface $self : NSObject")
for (m <- i.methods) { for (m <- i.methods) {
w.wl w.wl
writeDoc(w, m.doc) writeMethodDoc(w, m, idObjc.local)
writeObjcFuncDecl(m, w) writeObjcFuncDecl(m, w)
w.wl(";") w.wl(";")
} }
......
...@@ -24,6 +24,7 @@ import djinni.syntax.Error ...@@ -24,6 +24,7 @@ import djinni.syntax.Error
import djinni.writer.IndentWriter import djinni.writer.IndentWriter
import scala.language.implicitConversions import scala.language.implicitConversions
import scala.collection.mutable import scala.collection.mutable
import scala.util.matching.Regex
package object generatorTools { package object generatorTools {
...@@ -416,6 +417,15 @@ abstract class Generator(spec: Spec) ...@@ -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) { def writeDoc(w: IndentWriter, doc: Doc) {
doc.lines.length match { doc.lines.length match {
case 0 => case 0 =>
......
...@@ -6,6 +6,9 @@ _varname_record_ = record { ...@@ -6,6 +6,9 @@ _varname_record_ = record {
} }
_varname_interface_ = interface +c { _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_; _rmethod_(_r_arg_: _varname_record_): _varname_record_;
_imethod_(_i_arg_: _varname_interface_): _varname_interface_; _imethod_(_i_arg_: _varname_interface_): _varname_interface_;
} }
...@@ -13,6 +13,11 @@ class VarnameInterface { ...@@ -13,6 +13,11 @@ class VarnameInterface {
public: public:
virtual ~VarnameInterface() {} 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 VarnameRecord _rmethod_(const VarnameRecord & _r_arg_) = 0;
virtual std::shared_ptr<VarnameInterface> _imethod_(const std::shared_ptr<VarnameInterface> & _i_arg_) = 0; virtual std::shared_ptr<VarnameInterface> _imethod_(const std::shared_ptr<VarnameInterface> & _i_arg_) = 0;
......
...@@ -8,6 +8,11 @@ import javax.annotation.CheckForNull; ...@@ -8,6 +8,11 @@ import javax.annotation.CheckForNull;
import javax.annotation.Nonnull; import javax.annotation.Nonnull;
public abstract class VarnameInterface { public abstract class VarnameInterface {
/**
* We should also rewrite parameter names in docstrings.
* RArg should be rewritten.
* _i_arg_ should not.
*/
@Nonnull @Nonnull
public abstract VarnameRecord Rmethod(@Nonnull VarnameRecord RArg); public abstract VarnameRecord Rmethod(@Nonnull VarnameRecord RArg);
......
...@@ -8,6 +8,11 @@ ...@@ -8,6 +8,11 @@
@interface DBVarnameInterface : NSObject @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; - (nonnull DBVarnameRecord *)Rmethod:(nonnull DBVarnameRecord *)RArg;
- (nullable DBVarnameInterface *)Imethod:(nullable DBVarnameInterface *)IArg; - (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