我没有找到关于应该在类和__init__文档字符串中记录什么的最佳实践.有时我发现构造函数参数已经在docstring类中记录,有时会在__init__docstring 中描述.我更喜欢在类docstring中描述构造,因为这是您在创建新实例时调用的内容.但是应该在__init__docstring方法中记录什么呢？
编辑:
我知道google styleguide和google docstring样式示例,但两者都没有回答我的问题.文档字符串样式的例子确实说
该
__init__方法可以记录在类级别docstring中,也可以记录在__init__方法本身的docstring中.任何一种形式都是可以接受的,但这两种形式不应混合.选择一种约定来记录__init__方法并与之保持一致.
但是如果我选择将__init__函数的docstring 放入类级docstring中,那么__init__docstring 应该包含什么？
我找不到如何用C编写我的意思是我知道的意见//和/* */,我的意思是我在哪里可以找到好的做法？就像我有一个函数一样,我如何编写@param variable is the value bla bla,就像在Java中完成一样？
这有什么标准吗？或者我可以像在Java中那样做吗？
有没有办法做到这一点？
我有swashbuckle为我的其他API生成内容但我不相信它适用于SignalR.
我一直在搜索这个问题,要么我没有使用正确的搜索条件,要么我错过了一些东西.
我试图弄清楚是否可以使用PHPdoc来定义对象返回的变量.
说我有以下课程:
class SomeClass {
public function staffDetails($id){
$object = new stdClass();
$object->type = "person";
$object->name = "dave";
$object->age = "46";
return $object;
}
}
现在,定义输入参数很容易.
/**
* Get Staff Member Details
*
* @param string $id staff id number
*
* @return object
*/
class SomeClass {
public function staffDetails($id){
$object = new stdClass();
$object->type = "person";
$object->name = "dave";
$object->age = "46";
return $object;
}
}
问题是是否有类似的事情来定义相关方法返回的对象的输出变量,以便另一个程序员不必打开这个类并手动查看方法以查看返回对象返回的内容？
该函数的GNU libc文档abort包含以下通知:
未来变更警告:建议的联邦审查规定可能禁止我们向您提供有关调用此功能的可能性的信息.我们需要说这不是终止程序的可接受方式.
呃,什么？
我找到了一个七岁的Reddit讨论这个问题.看来该通知是由Richard Stallman在1995年提出的 - 所以它已经存在了一段时间.然而,除了1999年的邮件列表线程声称这是一个笑话,我找不到任何进一步的信息.
那么:这只是一个由rms投入的复活节彩蛋吗？或者它是否严重(虽然可能不再相关)？如果是这样,它指的是什么？
相同功能的Open Group POSIX文档不包含任何类似的内容,也没有我查阅的任何手册页.
我一直在尝试使用JSDoc记录以下代码:
/**
* @module person
*/
/**
* A human being.
* @class
* @param {string} name
*/
function Person(name){
this.name = name
}
Person.prototype = new function(){
var amount_of_limbs = 4;
/**
* Introduce yourself
*/
this.greet = function(){
alert("Hello, my name is " + this.name + " and I have " + amount_of_limbs + " limbs");
}
}
但是greet在最终的JSDoc文档中找不到该方法.我究竟做错了什么？
javascript documentation-generation code-documentation jsdoc jsdoc3
我似乎找不到任何一个,我唯一能找到的就是这个:https: //code.google.com/p/selenium/wiki/WebDriverJs
但它更像是一个指南.不是所有功能的文档.它缺乏例如文档Webdriver.Window或类似的东西getWindowHandles()
documentation selenium code-documentation node.js selenium-webdriver
因为-->是perl6中签名中声明返回类型的首选方法,我想知道是否可以将函数签名的代码放入其中C<...>.
例如 C<foo(Int $a --> Bool)>
我正在为浏览器应用程序的工作编写自己的库,我遇到了同样的问题,决定如何评论代码.
我正在尝试遵循JsDoc语法,但可能会继续使用Google Closure Compiler方式.我可能最终在文档中使用了两个@return和@returns标签,只是为了便携(当我设置文档的自动生成时).
现在,问题是,如何记录函数中自定义匿名对象的返回？例如:
return {
username: 'username',
password: 'password',
enabled: true
};
JsDoc有一个示例,说明如何记录@param以期望具有某些字段的对象,而不是@returns标记.同样,Google Closure Compiler记录类型的文档也很模糊,没有示例可以解决.
我有一些REST服务(使用和生成application/json),我用它@TypeHint来生成文档.
现在我有这样的事情:
import javax.ws.rs.core.Response;
...
@Path("/path")
public class MyClass {
@GET
@TypeHint(MyResponse.class)
public Response getIt() {
MyResponse resp = ... ;
return MyBuilder.build(resp);
}
}
但是MyResponse是一个包装List<MyType>.
我的build方法MyResponse看起来像这样:
public static Response build(Serializable payload) {
return Response.ok(msr).header(...).build();
}
我想直接使用List<MyType>而不是MyResponse.TypeHint在以下代码中使用哪种方法最好？
@GET
@TypeHint(/* TODO */)
public Response getIt() {
List<MyType> myList = ... ;
return MyBuilder.build(myList);
}
我在考虑以下选项:
@TypeHint(List.class)@TypeHint(MyType.class)@TypeHint(List<MyType>.class) - >遗憾的是,由于Java类型擦除,这不起作用.题:
3号有没有有效的替代方案？ …