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