jackmiwamiwa devblog

フロントエンドをメインに行ったことをまとめていくサイトになります。

JSDocを使用して、レビュー者に対して見やすいコードを心がける

JavaScirpt

JSDocの書き方がいまいちわかっておらず、いろいろと調べたのでその時にメモになります。

環境

参考リンク

qiita.com

daa-kitamura.ssl-lolipop.jp

vue-styleguidist.github.io

実装したコードの一部

バリデーションのチェックコンポーネント

/**
 * 必須部分が入力されているか
 * @param { string } value 入力されている値
 * @return { boolean } バリデーション通りになっているか
 */
export const checkRequired = (value) => {
  return !!value
}

propsの値の例

<script setup>
/**
 * 親から送られてきた変数の指定
 * @param { string } inputType inputのtype。現時点では「text」か「select」
 * @param { string } value フォームの値
 * @param { string } objectName App.vueにあるどこのobjectの値か
 * @param { boolean } isError そのフォームがエラーか
 * @param { string } [inputTitle] inputの上に表示するテキスト
 * @param { string } [inputNote] inputの右側に表示するテキスト「点・語など」
 * @param { string[] | null } [selectValueList=null] selectで表示を行う際に表示する中身
 * @param { string | null } [maxLength=null] 最大何文字まで表示をさせるか
 * @param { boolean } [full=false] inputのサイズを横幅いっぱいにしたい時に使用
 * @param { function } [rule="(value) => !!value"] エラー表示のするための処理
 */
defineProps({
  /**
   * @values text, select
   */
  inputType: {
    type: String,
    required: true,
  },
  value: {
    type: String,
    required: true,
  },
  objectName: {
    type: String,
    required: true,
  },
  isError: {
    type: Boolean,
    required: true,
  },
  inputTitle: {
    type: String,
    required: false,
    default: "",
  },
  inputNote: {
    type: String,
    required: false,
    default: "",
  },
  selectValueList: {
    type: Array,
    required: false,
    default: null,
  },
  maxLength: {
    type: Number,
    required: false,
    default: null,
  },
  full: {
    type: Boolean,
    required: false,
    default: false,
  },
  rule: {
    type: Function,
    required: false,
    default: (value) => checkRequired(value),
  },
})
</script>

emitの記載例

<script setup>
/**
 * 親から送られてきた関数の指定
 * @event change-form-value フォームの値を変更するための関数
 */
const emit = defineEmits(["change-form-value"])
</script>

関数の記載例

/**
 * 「英語」のエリアのフォームにエラーはないか
 * @return { boolean } エラーがない場合、falseを返却する
 */
const checkEnglishError = () => {
  const { english } = state
  const { level, toice, toefl } = english
  const isLevel = checkRequired(level)
  const isToice = checkRequired3Digits(toice)
  const isToefl = checkRequired3Digits(toefl)
  return !isLevel || !isToice || !isToefl
}

stateの値

/**
 * 「レベル」で表示されるセレクトの一覧
 * @property { Object } english 「英語」のオブジェクトの値
 * @property { string } english.level 「レベル」で選択された値
 * @property { string } english.toice 「toice」で入力された値
 * @property { string } english.toefl 「toefl」で入力された値
 * @property { Object[] } other 「その他の言語」のオブジェクト一覧の値
 * @property { string } other.id uuidを使用したユニークなid
 * @property { string } other.lang 「言語」で選択された値
 * @property { boolean } other.otherFlg 「言語」で「その他」が選択されているか
 * @property { string } other.otherValue 「その他」の値
 * @property { string } other.level 「レベル」で選択された値
 */
const state = reactive({
  english: {
    level: "",
    toice: "",
    toefl: "",
  },
  other: [
    {
      id: uuidv4(),
      lang: "",
      otherFlg: false,
      otherValue: "",
      level: "",
    },
  ],
})

記載したこと

  • 引数は @param
  • 関数などで返り値がある場合は @return
  • 定数は @property
  • emitの場合は @event
  • JavaScirptの都合上、何か指定の文字列のみを入れたい場合については@values