• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2023 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16export namespace Comment {
17  export enum JsDocTag {
18    SYSCAP = 'syscap',
19    SINCE = 'since',
20    FORM = 'form',
21    CROSS_PLAT_FORM = 'crossplatform',
22    SYSTEM_API = 'systemapi',
23    STAGE_MODEL_ONLY = 'stagemodelonly',
24    FA_MODEL_ONLY = 'famodelonly',
25    DEPRECATED = 'deprecated',
26    USEINSTEAD = 'useinstead',
27    TYPE = 'type',
28    CONSTANT = 'constant',
29    PERMISSION = 'permission',
30    THROWS = 'throws',
31    ATOMIC_SERVICE = 'atomicservice',
32    KIT = 'kit',
33    FILE = 'file',
34    PARAM = 'param',
35    RETURNS = 'returns'
36  }
37
38  export interface JsDocProcessorInterface {
39    (jsDocInfo: JsDocInfo, commentTag: Comment.CommentTag): void;
40  }
41
42  export class JsDocInfo {
43    description: string = ''; // jsdoc的整体描述
44    syscap: string = ''; // @syscap标签--api的系统能力
45    since: string = '-1'; // @since标签--api的起始版本
46    isForm: boolean = false; // @form标签--api是否支持卡片应用
47    isCrossPlatForm: boolean = false; // @crossplatform标签--api是否支持跨平台
48    isSystemApi: boolean = false; // @systemapi--api是否是系统api
49    modelLimitation: string = ''; // @stagemodelonly或@famodelonly--api的使用模型限制
50    deprecatedVersion: string = '-1'; // @deprecated标签--api的废弃版本
51    useinstead: string = ''; // @useinstead标签--api的替换接口
52    permissions: string = ''; // @permission标签--api的权限
53    errorCodes: number[] = []; // @throws标签--api的错误码
54    typeInfo: string = ''; // @type标签--标注的类型信息
55    isConstant: boolean = false; // @constant标签--标注api为常量
56    isAtomicService: boolean = false; //@atomicservice--标注是否为高阶API
57    kit: string = '';
58    fileTagContent: string = 'NA';
59    tags: CommentTag[] | undefined = undefined;
60
61    constructor() {}
62
63    setDescription(description: string): JsDocInfo {
64      this.description = description;
65      return this;
66    }
67
68    getDescription(): string {
69      return this.description;
70    }
71
72    setSyscap(syscap?: string): JsDocInfo {
73      if (syscap) {
74        this.syscap = syscap;
75      }
76      return this;
77    }
78
79    getSyscap(): string {
80      return this.syscap;
81    }
82
83    setSince(since: string): JsDocInfo {
84      this.since = since;
85      return this;
86    }
87
88    getSince(): string {
89      return this.since;
90    }
91
92    setIsForm(isForm: boolean): JsDocInfo {
93      this.isForm = isForm;
94      return this;
95    }
96
97    getIsForm(): boolean {
98      return this.isForm;
99    }
100
101    setIsCrossPlatForm(isCrossPlatForm: boolean): JsDocInfo {
102      this.isCrossPlatForm = isCrossPlatForm;
103      return this;
104    }
105
106    getIsCrossPlatForm(): boolean {
107      return this.isCrossPlatForm;
108    }
109
110    setIsSystemApi(isSystemApi: boolean): JsDocInfo {
111      this.isSystemApi = isSystemApi;
112      return this;
113    }
114
115    getIsSystemApi(): boolean {
116      return this.isSystemApi;
117    }
118
119    setIsAtomicService(isAtomicService: boolean): JsDocInfo {
120      this.isAtomicService = isAtomicService;
121      return this;
122    }
123
124    getIsAtomicService(): boolean {
125      return this.isAtomicService;
126    }
127
128    setModelLimitation(modelLimitation: string): JsDocInfo {
129      this.modelLimitation = modelLimitation;
130      return this;
131    }
132
133    getModelLimitation(): string {
134      return this.modelLimitation;
135    }
136
137    setDeprecatedVersion(deprecatedVersion: string): JsDocInfo {
138      this.deprecatedVersion = deprecatedVersion;
139      return this;
140    }
141
142    getDeprecatedVersion(): string {
143      return this.deprecatedVersion;
144    }
145
146    setUseinstead(useinstead: string): JsDocInfo {
147      this.useinstead = useinstead;
148      return this;
149    }
150
151    getUseinstead(): string {
152      return this.useinstead;
153    }
154
155    setPermission(permissions: string): JsDocInfo {
156      this.permissions = permissions;
157      return this;
158    }
159
160    getPermission(): string {
161      return this.permissions;
162    }
163
164    addErrorCode(errorCode: number): JsDocInfo {
165      this.errorCodes.push(errorCode);
166      return this;
167    }
168
169    getErrorCode(): number[] {
170      return this.errorCodes;
171    }
172
173    setTypeInfo(typeInfo: string): JsDocInfo {
174      this.typeInfo = typeInfo;
175      return this;
176    }
177
178    getTypeInfo(): string {
179      return this.typeInfo;
180    }
181
182    setIsConstant(isConstant: boolean): JsDocInfo {
183      this.isConstant = isConstant;
184      return this;
185    }
186
187    getIsConstant(): boolean {
188      return this.isConstant;
189    }
190
191    setKit(kit: string): JsDocInfo {
192      this.kit = kit;
193      return this;
194    }
195
196    getKit(): string {
197      return this.kit;
198    }
199
200    setFileTagContent(isFile: string): JsDocInfo {
201      this.fileTagContent = isFile;
202      return this;
203    }
204
205    getFileTagContent(): string {
206      return this.fileTagContent;
207    }
208
209    setTags(tags: CommentTag[]): JsDocInfo {
210      this.tags = tags;
211      return this;
212    }
213
214    removeTags(): JsDocInfo {
215      this.tags = undefined;
216      return this;
217    }
218
219    addTag(tag: CommentTag): JsDocInfo {
220      if (!this.tags) {
221        this.tags = [];
222      }
223      this.tags.push(tag);
224      return this;
225    }
226
227    getTags(): CommentTag[] | undefined {
228      return this.tags;
229    }
230  }
231
232  /**
233   * 注释信息
234   */
235  export interface CommentInfo {
236    /**
237     * 原始注释文本
238     */
239    text: string;
240
241    /**
242     * 是否为多行注释
243     */
244    isMultiLine: boolean;
245
246    /**
247     * true为头注释，false为未注释
248     */
249    isLeading: boolean;
250
251    /**
252     * 注释描述
253     */
254    description: string;
255
256    /**
257     * 注释标签列表
258     */
259    commentTags: Array<CommentTag>;
260
261    /**
262     * 结构化的注释对象
263     */
264    parsedComment: any;
265
266    /**
267     * 注释起始位置
268     */
269    pos: number;
270
271    /**
272     * 注释结束位置
273     */
274    end: number;
275
276    /**
277     * 是否忽略此注释
278     */
279    ignore: boolean;
280
281    /**
282     * 是否是api注释
283     */
284    isApiComment: boolean;
285
286    /**
287     * 是否为特殊日志。例如，为了增加空行而添加的特殊单行日志。
288     */
289    isInstruct: boolean;
290
291    /**
292     * 是否为文件的jsdoc
293     */
294    isFileJsDoc: boolean;
295  }
296
297  export interface CommentTag {
298    /**
299     * 注释标签，例如 @param
300     */
301    tag: string;
302
303    /**
304     * 标签名称, 例如 @param name
305     */
306    name: string;
307
308    /**
309     *  类型, 例如 @param { type } name
310     */
311    type: string;
312
313    /**
314     * 是否可选
315     */
316    optional: boolean;
317
318    /**
319     * 描述
320     */
321    description: string;
322
323    /**
324     * 默认值
325     */
326    defaultValue?: string;
327
328    /**
329     * 原始注释内容
330     */
331    source: string;
332
333    /**
334     * 行号
335     */
336    lineNumber: number;
337
338    /**
339     * tag 的描述可能有多行, 首行包含tag信息，其余包含tag的描述信息。
340     */
341    tokenSource: Array<Comment.CommentSource>;
342  }
343
344  export interface CommentSource {
345    /**
346     * 行号
347     */
348    number: number;
349
350    /**
351     * 原始注释行
352     */
353    source: string;
354
355    /**
356     * 注释被拆分后的对象
357     */
358    tokens: CommentToken;
359  }
360
361  /**
362   * 注释被拆分为以下部分:
363   * |start|delimiter|postDelimiter|tag|postTag|name|postName|type|postType|description|end\
364   */
365  export interface CommentToken {
366    /**
367     * 注释每行起始字符
368     */
369    start: string;
370
371    /**
372     * 注释行开始定界符
373     */
374    delimiter: string;
375
376    /**
377     * 定界符之后的字符
378     */
379    postDelimiter: string;
380
381    /**
382     * 标签
383     */
384    tag: string;
385
386    /**
387     * 标签之后的字符
388     */
389    postTag: string;
390
391    /**
392     * 标签名称
393     */
394    name: string;
395
396    /**
397     * 标签后的字符
398     */
399    postName: string;
400
401    /**
402     * 类型
403     */
404    type: string;
405
406    /**
407     * 类型后的字符
408     */
409    postType: string;
410
411    /**
412     * 描述
413     */
414    description: string;
415
416    /**
417     * 结束字符
418     */
419    end: string;
420
421    /**
422     * 行结束字符
423     */
424    lineEnd: string;
425  }
426}
427