JavaScript Auto-documentazione del codice in cui sono i API strumenti Documenti?

Question

Questi due concetti sembrare contro-intuitivo. C'è una parte della tesi che vede il danno che i commenti fanno per la leggibilità, e le violazioni dei DRY (se i commenti sono anche tenuti aggiornati). Tuttavia, capovolgere la moneta e non v'è una necessità di fornire una buona documentazione API per il codice in modo che altri possono utilizzare le librerie.

Ogni utensile (JSDoc, pDoc, ecc) ho visto che è stato progettato per generare documentazione API utilizza una quantità estrema di spazio per fornire tale documentazione. Ho bisogno di fornire documentazione delle API, che non ho bisogno è di avere la metà del mio LOC essere appositamente formattato commentando così JSDoc possa leggerlo.

Al momento sto considerando uno strumento Markdown base come Jekyll e la cartella di mettere questa documentazione in un / doc , totalmente rimozione dal mio codice. Qualcun altro ha trovato un approccio a questo problema che ha lavorato per loro?

Answer 1

Sfinge è uno strumento di documentazione per molte lingue, che presuppone che si scriverà la documentazione per lo più in file esterni . Ancora ha un'estensione autodoc, che permette di estrarre la documentazione dai commenti nel codice.

Personalmente trovo più conveniente per avere la documentazione API proprio vicino il codice, come mi aiuta a mantenere fino ad oggi. Inoltre, le altre persone che lavorano su quel codice saranno in grado di avere la documentazione solo quando ne hanno bisogno, senza dover navigare tra i file esterni. Francamente non vedo nulla di male ad avere la maggior parte delle linee di codice che sono i commenti:. Redattori di solito commenti colore diverso e ti permettono di ignorarli, se si desidera