logi sisse meist KKK

Milline on parim formaat JavaScripti koodi dokumenteerimiseks ja miks? JSdoc, PDoc, mõni muu või hoopis enda mõeldud standard? Ma ise kasutan PDoc formaati, kuid huvitab, et mida teised kasutavad ja eriti, et miks just nii.

küsitud Sep 01 '10 at 21:09

Andris's gravatar image

Andris
2553310


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.

link

vastatud Sep 10 '10 at 13:30

Rene%20Saarsoo's gravatar image

Rene Saarsoo ♦♦
1.1k101121

Seesama clone näide on just päris hea PDoc'i ilmestamiseks, kuna parser ei saa funktsiooni deklaratsiooni alusel kuidagi arvata, et tegu on Array klassi meetodiga. Funktsioonide ja objektide nimetuste kordamine on muidugi tüütu overhead, kuid see päästab näiteks ettekirjutatud kodeerimisstiilist - stiil ei pea olema dokumenteerimise parserile arusaadav. Lisaks kasutab PDoc HTML'i asemel Markdown'i ja see on muidugi ka väga mugav.

(Sep 11 '10 at 20:07) Andris

Niiviisi eraldiseisvana vaadates on parseril jah raske aru saada, aga eespool failis on öeldud "class Array" ja selle alusel võiks kenasti järeldada, et kõik järgnevad funktsioonid on selle klassi meetodid. Nii on see ju 99% juhtudest; eraldi markupiga võiks tähistada hoopis erandjuhud kui see nii pole.

(Sep 22 '10 at 07:55) Rene Saarsoo ♦♦

Maitse asi vist. PDoci süntaks kasutab mõnevõrra ebatraditsioonilist lähenemist. Java või PHP(doc) maailmast tulnud inimesel on JSDoc-ist lihtsam aru saada. Pealegi toimub JSDoci projektis vilgas arendustegevus juba pikemat aega. Oht, et nad ootamatult ära kaovad, on üsna väike.

link

vastatud Sep 02 '10 at 11:43

user-197%20%28google%29's gravatar image

user-197 (google)
2314

Mu eelmisest vastusest saati on juhtunud see, et kirjutasin ise JavaScripti dokumenteerimiseks programmi JSDuck. See suuresti lahendab probleemid mida ma eelnevalt kirjeldasin.

Hetkel on JSDuck suunatud ExtJS-i raamistikus kirjutatud koodi dokumenteerimisele, kuid pole otsest takistust seda ka väljaspool ExtJS-i kasutada. Oleksin üsnagi huvitatud tagasisidest kui kellegil selline huvi on.

link

vastatud Apr 08 '11 at 14:35

Rene%20Saarsoo's gravatar image

Rene Saarsoo ♦♦
1.1k101121

Sinu vastus
lülita eelvaade

Jälgi seda küsimust

By Email:

Pärast sisselogimist saad tellida muudatuse teavitusi siit

By RSS:

Answers

Answers and Comments

Markdown Basics

  • *kaldkiri* või __kaldkiri__
  • **paks kiri** või __paks kiri__
  • link:[tekst](http://url.com/ "pealkiri")
  • pilt?![alt tekst](/path/img.jpg "pealkiri")
  • nummerdatud nimekiri: 1. Foo 2. Bar
  • to add a line break simply add two spaces to where you would like the new line to be.
  • põhilised HTML märgendid on samuti toetatud

Pinu tööpakkumised

kõik pakkumised »

Küsimuse sildid:

×18
×4

küsitud: Sep 01 '10 at 21:09

nähtud: 3,576 korda

viimati uuendatud: Apr 08 '11 at 14:35

Litsents: Creative Commons Attribution License | Kontakt: info@pinu.ee