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