草庐IT

javascript - 关于记录 JavaScript : JS types 的问题

coder 2025-03-14 原文

考虑到我将来要和一个更大的团队一起工作，我正在尝试自学一些前端语言的基本注释和文档原则。目前我正在研究 JS。

在大多数情况下，我使用 Google's Style Guide作为首选，但我还有一些问题。

假设我有一个像这样的 ajax 函数:

function initFunction(src, wrapper) {
  $.getJSON(src, {
    format: "json"
  }).done(function(data) {
    var wrapper = $(wrapper),
      contents = callAnotherFunction($(data)[0]);

    // Populates the wrapper element.
    wrapper.append(contents );

  }).fail(function(jqXHR, textStatus, errorThrown) {
    alert(textStatus + ": " + errorThrown);
  });
}

函数有两个@param，src和wrapper。这里有一些问题。

然后，callAnotherFunction() 将一个对象作为参数，它应该返回一些 HTML。

  1. src 的类型是什么？考虑到它是 JSON，{Object}?
  2. 包装器的类型是什么？考虑到它是一个值，例如 "#myId"，String?
  3. 这个函数的返回类型是什么？这是一个 void 函数，但我不知道如何调用它的返回类型。它是否返回空值？
  4. 可以附加到元素的 HTML 类型是什么？它是 String 吗？
  5. 显示所有这些的 JSDoc 约定是什么？是这样的吗？

/** * 这是此功能的说明。它获取一个 JSON 文件，将其用作 * 一个 jQuery 对象，然后用新数据调用另一个函数。 * @param {Object} 要解析的 src JSON 文件。 * @param {String} 包装器 HTML 元素用作输出的包装器。 * @return {空} */

最佳答案

  1. 参数的类型与其表示的内容无关，而是参数的 JavaScript 类型。在你的情况下 src 是一个包含 url 的字符串(检索 url 检索 JSON 并不重要)所以类型是字符串。更多信息 here .
  2. 是的，这是一个字符串。
  3. 如果函数没有返回值，就不要在 JSDoc 中提及它。
  4. 根据 JQuery documentation它是:

Type: htmlString or Element or Array or jQuery

DOM element, array of elements, HTML string, or jQuery object to insert at the end of each element in the set of matched elements.

因此，这取决于您要将您的函数记录为接受的内容。如果你想将其记录为接受多种类型，你 use parentheses and the | character (示例如下)。

  1. 关闭，但您不需要返回类型。有些人还在描述和参数之间放置一个空行，但解析器不需要这样做。

    /**
 * This is a description of this function. It gets a JSON file, uses it as 
 * a jQuery object, and then call another function with the new data.
 *
 * @param  {Object} src     JSON file to parse.
 * @param  {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output.
 */
function initFunction(src, wrapper) {
// ...

    在上面，我们指出 wrapper 可以是字符串、jQuery 对象或 DOMElement。我们没有深入了解它可能是一个数组的细节，也没有深入了解该字符串是选择器还是 HTML 片段。描述需要处理这个问题。有很多选择，您可能不得不求助于 {*}。

    如果解析器可能无法判断这是否是一个函数，您还可以添加 @function tag :

    /**
 * This is a description of this function. It gets a JSON file, uses it as 
 * a jQuery object, and then call another function with the new data.
 *
 * @function
 *
 * @param  {Object} src     JSON file to parse.
 * @param  {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output.
 */
var initFunction = function(src, wrapper) {
// ...

    根据上下文，您可能更喜欢 @method 而不是 @function(它们是同义词)。

关于javascript - 关于记录 JavaScript : JS types 的问题，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/33452587/

javascriptcodefunctionwrappernaming-conventionsconventions

有关javascript - 关于记录 JavaScript : JS types 的问题的更多相关文章

  1. ruby - 在 64 位 Snow Leopard 上使用 rvm、postgres 9.0、ruby 1.9.2-p136 安装 pg gem 时出现问题 - 2

    我想为Heroku构建一个Rails3应用程序。他们使用Postgres作为他们的数据库，所以我通过MacPorts安装了postgres9.0。现在我需要一个postgresgem并且共识是出于性能原因你想要pggem。但是我对我得到的错误感到非常困惑当我尝试在rvm下通过geminstall安装pg时。我已经非常明确地指定了所有postgres目录的位置可以找到但仍然无法完成安装:$envARCHFLAGS='-archx86_64'geminstallpg--\--with-pg-config=/opt/local/var/db/postgresql90/defaultdb/po

  2. ruby - 通过 rvm 升级 ruby​​gems 的问题 - 2

    尝试通过RVM将RubyGems升级到版本1.8.10并出现此错误:$rvmrubygemslatestRemovingoldRubygemsfiles...Installingrubygems-1.8.10forruby-1.9.2-p180...ERROR:Errorrunning'GEM_PATH="/Users/foo/.rvm/gems/ruby-1.9.2-p180:/Users/foo/.rvm/gems/ruby-1.9.2-p180@global:/Users/foo/.rvm/gems/ruby-1.9.2-p180:/Users/foo/.rvm/gems/rub

  3. ruby - 通过 RVM (OSX Mountain Lion) 安装 Ruby 2.0.0-p247 时遇到问题 - 2

    我的最终目标是安装当前版本的RubyonRails。我在OSXMountainLion上运行。到目前为止，这是我的过程:已安装的RVM$\curl-Lhttps://get.rvm.io|bash-sstable检查已知(我假设已批准)安装$rvmlistknown我看到当前的稳定版本可用[ruby-]2.0.0[-p247]输入命令安装$rvminstall2.0.0-p247注意:我也试过这些安装命令$rvminstallruby-2.0.0-p247$rvminstallruby=2.0.0-p247我很快就无处可去了。结果:$rvminstall2.0.0-p247Search

  4. ruby - Sinatra:运行 rspec 测试时记录噪音 - 2

    Sinatra新手；我正在运行一些rspec测试，但在日志中收到了一堆不需要的噪音。如何消除日志中过多的噪音？我仔细检查了环境是否设置为:test，这意味着记录器级别应设置为WARN而不是DEBUG。spec_helper:require"./app"require"sinatra"require"rspec"require"rack/test"require"database_cleaner"require"factory_girl"set:environment,:testFactoryGirl.definition_file_paths=%w{./factories./test/

  5. ruby - Fast-stemmer 安装问题 - 2

    由于fast-stemmer的问题，我很难安装我想要的任何ruby​​gem。我把我得到的错误放在下面。Buildingnativeextensions.Thiscouldtakeawhile...ERROR:Errorinstallingfast-stemmer:ERROR:Failedtobuildgemnativeextension./System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/bin/rubyextconf.rbcreatingMakefilemake"DESTDIR="cleanmake"DESTDIR=

  6. ruby - 安装 Ruby 时遇到问题(无法下载资源 "readline--patch") - 2

    当我尝试安装Ruby时遇到此错误。我试过查看this和this但无济于事➜~brewinstallrubyWarning:YouareusingOSX10.12.Wedonotprovidesupportforthispre-releaseversion.Youmayencounterbuildfailuresorotherbreakages.Pleasecreatepull-requestsinsteadoffilingissues.==>Installingdependenciesforruby:readline,libyaml,makedepend==>Installingrub

  7. ruby-on-rails - Rails 5 Active Record 记录无效错误 - 2

    我有两个Rails模型，即Invoice和Invoice_details。一个Invoice_details属于Invoice，一个Invoice有多个Invoice_details。我无法使用accepts_nested_attributes_forinInvoice通过Invoice模型保存Invoice_details。我收到以下错误:(0.2ms)BEGIN(0.2ms)ROLLBACKCompleted422UnprocessableEntityin25ms(ActiveRecord:4.0ms)ActiveRecord::RecordInvalid(Validationfa

  8. java - 从 JRuby 调用 Java 类的问题 - 2

    我正在尝试使用boilerpipe来自JRuby。我看过guide从JRuby调用Java，并成功地将它与另一个Java包一起使用，但无法弄清楚为什么同样的东西不能用于boilerpipe。我正在尝试基本上从JRuby中执行与此Java等效的操作:URLurl=newURL("http://www.example.com/some-location/index.html");Stringtext=ArticleExtractor.INSTANCE.getText(url);在JRuby中试过这个:require'java'url=java.net.URL.new("http://www

  9. ruby-on-rails - 简单的 Ruby on Rails 问题——如何将评论附加到用户和文章？ - 2

    我意识到这可能是一个非常基本的问题，但我现在已经花了几天时间回过头来解决这个问题，但出于某种原因，Google就是没有帮助我。(我认为部分问题在于我是一个初学者，我不知道该问什么......)我也看过O'Reilly的RubyCookbook和RailsAPI，但我仍然停留在这个问题上.我找到了一些关于多态关系的信息，但它似乎不是我需要的(尽管如果我错了请告诉我)。我正在尝试调整MichaelHartl'stutorial创建一个包含用户、文章和评论的博客应用程序(不使用脚手架)。我希望评论既属于用户又属于文章。我的主要问题是:我不知道如何将当前文章的ID放入评论Controller。

  10. 【高数】用拉格朗日中值定理解决极限问题 - 2

    首先回顾一下拉格朗日定理的内容：函数f(x)是在闭区间[a,b]上连续、开区间(a,b)上可导的函数，那么至少存在一个，使得:通过这个表达式我们可以知道，f(x)是函数的主体，a和b可以看作是主体函数f(x)中所取的两个值。那么可以有，  也就意味着我们可以用来替换 这种替换可以用在求某些多项式差的极限中。方法： 外层函数f(x)是一致的，并且h(x)和g(x)是等价无穷小。此时，利用拉格朗日定理，将原式替换为 ，再进行求解，往往会省去复合函数求极限的很多麻烦。使用要注意：1.要先找到主体函数f(x)，即外层函数必须相同。2.f(x)找到后，复合部分是等价无穷小。3.要满足作差的形式。如果是加

随机推荐