JavaScripti koodi dokumenteerimine

Minu jaoks on põhikriteeriumiks, et dokumenteerimine oleks võimalikult kerge. Kui dokumentatsiooni generaator nõuab, et sa sisestaksid hulgaliselt spetsiaalset markupi, siis muutub dokumenteerimine piinarikkaks ja keegi ei viitsi seda teha.

Kuid peab ütlema, et seni on mul veel leidmata vahend, mis oleks piisavalt mugav. Näiteks JSDoc ja analoogsete vahendite juures on üheks suuremaks probleemiks, et sa pead dokumentatsiooni sisse kirjutama HTML-i, näiteks nii:

/**
 * This is my function.
 *
 * <p>It does three things:
 *
 * <ul>
 * <li>First thing</li>
 * <li>Second thing</li>
 * <li>Third thing</li>
 * </li>
 *
 * @param {String} input  <b>NB!</b> must be in uppercase.
 */
function blah(input) {
}

PDoc näikse vähemasti selle koha pealt oluliselt parem. Kuid esmakordsel süvenemisel PDoc-i hakkas mulle kohe silma, et ma pean pidevalt üle kordama klassi ja funktsiooni nime. Näide PrototypeJS-i koodist:

/**
 *  Array#clone() -> Array
 *
 *  Returns a duplicate of the array, leaving the original array intact.
**/
function clone() {
  return slice.call(this, 0);
}

Parser võiks ju ise aru saada, et meetodi nimi on "clone" ja ta kuulub Array klassi.

Muidu tundub see PDoc päris tubli, aga ta õhkab minu jaoks kuidagi selle järele, et see on tehtud PrototypeJS-i dokumenteerimiseks ja mitte eriti millegiks muuks. (Aga see on pelgalt minu esmakordse pealevaatamise tunne.)

Ma ise kasutan ext-doc, kuna ma suurema osa koodist kirjutan ExtJS raamistikus. Põhimõtteliselt on tegu JSDoc derivaadiga, koos kõigi oma halbade külgedega, pluss veel mõned lisaks - aga vähemasti mõistab ta ExtJS-i koodi.