Question

我们应该使用什么标签来记录带有JSDoc的Angular JS组件？我在考虑使用@module，我是对的吗？

例如：

/**
* @module helloWorld
*
* @description AngularJS component to display a message with a name.
*
*/
angular.component('helloWorld', {
  bindings: {
    name: '@'
  },
  controller : function helloWorldCtrl () {
    this.logName = logName;

    /**
     * @function logName
     *
     * @param {string} msg - message to display with the name.
     *
     * @memberof helloWorld
     *
     * @description Log in the console the message with the name.
     *
     */
    function logName(msg) {
      console.log(msg + this.name);
    }
  },
  template : '<div><span ng-click="$ctrl.logName('Hi ')">{{$ctrl.name}}!</span></div>'
});

对于指令，服务和控制器，我会有同样的问题。除了我使用@memberof的方式对吗？

Answer 1

虽然JSDoc确实有@module，但这是一个“可见性”规范，我认为这不是你想要的。

@module标记将当前文件标记为自己的模块。除非另有说明，否则假定文件中的所有符号都是模块的成员。

哪些可能是真的，但也可能不是。

您需要记住的关键是这些注释应该充当面包屑跟踪，以便继承行为可以链接到文档中，并且编译器尽可能多地获取有关代码的信息。

因此，在查找如何记录此内容时，我会在Angular externs和import pandas as pd import numpy as np import matplotlib.pyplot as plt import datetime import matplotlib.dates class Sampler(): def __init__(self,df): self.df = df def resample(self, limits): print limits dt = limits[1] - limits[0] if (type(dt) != pd.tslib.Timedelta) and (type(dt) != datetime.timedelta): dt = datetime.timedelta(days=dt) print dt #see #http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases if dt > datetime.timedelta(hours=5): t = "H"; width=1./24 elif dt > datetime.timedelta(minutes=60): t = "15T"; width=15./(24.*60) elif dt > datetime.timedelta(minutes=5): t = "T"; width=1./(24.*60) elif dt > datetime.timedelta(seconds=60): t = "15S"; width=15./(24.*60*60) else: #dt < datetime.timedelta(seconds=60): t = "S"; width=1./(24.*60*60) self.resampled = pd.DataFrame() self.resampled['data'] = self.df.data.resample(t, how="mean") print t, len(self.resampled['data']) print "indextype", type(self.resampled.index[0]) print "limitstype", type(limits[1]) if type(limits[1]) == float or type(limits[1]) == np.float64 : dlowlimit = matplotlib.dates.num2date(limits[0]) duplimit = matplotlib.dates.num2date(limits[1]) print type(duplimit), duplimit self.resampled = self.resampled.loc[self.resampled.index <= duplimit] self.resampled = self.resampled.loc[self.resampled.index >= dlowlimit] else: self.resampled = self.resampled.loc[self.resampled.index <= limits[1]] self.resampled = self.resampled.loc[self.resampled.index >= limits[0]] return self.resampled.index,self.resampled['data'],width def update(self, ax): print "update" lims = ax.viewLim start, stop = lims.intervalx ax.clear() x,y,width = self.resample([start, stop]) ax.bar(x,y, width=width) ax.set_xlim([start, stop]) ax.callbacks.connect('xlim_changed', self.update) ax.figure.canvas.draw() times = pd.date_range(start='2017-01-11',periods=86400, freq='1S') df = pd.DataFrame(index = times) df['data'] = np.sort(np.random.randint(low=1300, high=1600, size=len(df.index)) )[::-1] + \ np.random.rand(len(df.index))*500 sampler = Sampler(df) x,y,width = sampler.resample( [df.index[0],df.index[-1] ] ) fig, ax = plt.subplots() ax.bar(x,y, width=width) ax.xaxis_date() # connect to limits changes ax.callbacks.connect('xlim_changed', sampler.update) plt.show() / @return / @type中查找部分以匹配;

@param

希望有所帮助！

Answer 2

首先在文档中定义单独的主题以列出所有模块。为此创建一个带有下一个注释的空文件：

/**
 * @namespace solution_name
 */

对于模块，可以使用此注释使每个模块在其seprarate html页面中定义

/**
 * @class solution_name.MyModule
 * @memberOf solution_name 
 */

服务注释将作为myModule页面文档的一部分添加

/**
 * @function myService
 * @memberOf solution_name.MyModule
 * @description This is an my service.
 */

控制器可以像这样进行装饰，也可以作为单独的单元列在模块文档页面中

/**
 * @class solution_name.MyModule.MyController
 */

要创建树结构以组合控制器，基于业务需求的服务，您还可以根据您的类/函数定义添加namespace属性

/**
 * @namespace MyApp.Controllers
 */

如何使用JSDoc注释AngularJS组件

2 个答案: