Как правильно задокументировать эти методы?

Question

[Aleksandr]

Есть у меня две функции, которые находятся в разных файлах.

В компоненте:

getPayInfoExtended(obj: any) {
    this.AS.getInfo(this.number).subscribe(res => {
      this.result = res;
    },
      error => {
        console.log(error)
      })
  }

И в сервисе:

getInfo(obj) {
    return this.http.post(`${this.url}getinfo?`, obj)
  }

Никогда до сих пор не пользовался JSDoc
Подскажите, каким образом правильно задокументировать этот код?

Comments

[Pavel Pikat]

Не вижу смысла его документировать - код слишком простой и не нужен в объяснении "почему".
Комментарии, которые отвечают на вопрос "что", а не "почему" - это трата времени. Название методов у вас отвечает на "что".

P.S Ну можно конечно метод в сервисе перемеиновать и дополнить инфо чего там возвращается, например getPayInfo

[Aleksandr]

Pavel Pikat, понял, тогда задам иначе вопрос.

Представим ситуацию, что все-таки нужно документировать.

[Pavel Pikat]

Aleksandr, эх, тогда это страдание какое-то когда заставляют без понимания зачем и почему

Так или иначе, советую посмотреть JSDoc cheatseet, там есть примеры того как можно описать параметры и возвращаемые данные.

Еще можно было бы сам код дополнить и написать принимаемый и возвращаемый тип у методов, например
getInfo(obj: MyDTO): Observable<MyResultDTO>

[Aleksandr]

Меня интересовал именно вопрос след характера:

Вот метод в сервисе и допустим я добавляю ему комментарий такого плана

/**
   * @description Получает такую-то информациюю
   * @param {object} obj Принимает на вход result {id, entityId}
   * @returns Возвращает объект с
   * @memberof AService
   */
  getinfo(obj) {
    console.log(obj)
    return this.http.post(`${this.url}getInfo?`, obj)
  }

В таком случае, я правильно понимаю, что метод в компоненте getPayInfoExtended уже вообще не нужно документировать?

[Дмитрий Лузанов]

Оффтоп, но вот это:

getPayInfoExtended(obj: any) {
    this.AS.getInfo(this.number).subscribe(res => {
      this.result = res;
    },
      error => {
        console.log(error)
      })
  }

рекомендую заменить на вот такое (вы не отписываетесь в классе компонента, это приведет к утечкам; вместо этого создавайте Observable потоки и в шаблоне компонента используйте пайп async):

public result$: Observable<T>

getPayInfoExtended(obj: any) {
    this.result$ = this.AS.getInfo(this.number).pipe(catchError(err => console.log(err)))
}

{{ result$ | async }}

[Дмитрий Лузанов]

И зачем вы передаете obj, если он не используется?

[Aleksandr]

Дмитрий Лузанов, я просто обрезал все лишнее, чтобы только по сути было, obj используется. Про потоки почитаю и воспользуюсь, спасибо