Uzyskiwanie wzorców projektowych jsdoc i Crockford, aby się dogadać

Question

Używam aplikacji Douglasa Crockforda design pattern do implementacji metod prywatnych, uprzywilejowanych i publicznych. W zasadzie wygląda mniej więcej tak (za pomocą RequireJS):

define(function() { 
    return function() { 
     var that = {}, 

     _init = function() { 
      // "constructor" 
     }, 

     _privateFn = function() { 
      return 42; 
     }; 

     that.publicFn = function() { 
      return 2 * _privateFn(); 
     }; 

     _init(arguments); 

     return that; 
    }; 
}); 

Jednak mam problemy z uzyskaniem jsdoc toolkit aby je analizować poprawnie. Grałem z adnotacjami @name i @memberOf (jak here), ale bez względu na to, co robię, po prostu nie mogę uzyskać funkcji do wyświetlenia.

Czy ktoś zna rozwiązanie?

Answer 1

Ok, ale w końcu zorientowaliśmy się. Oto, jak to zrobić:

/** 
* @name MyModule 
* @namespace 
*/ 
define(['MyModule'], (function() { 
    "use strict"; 

    var Clazz = function (config) { 
     var that = {}, 

     /** 
     * @private 
     * @type number 
     * @name MyModule#_privateField 
     * @field 
     */ 
     _privateField = 42, 

     /** 
     * Returns a private field 
     * 
     * @private 
     * @memberOf MyModule# 
     */ 
     _privateFn = function() { 
      return _privateField; 
     }; 

     /** 
     * Uppercases a string value. 
     * 
     * @public 
     * @name MyModule#publicFn 
     * @function 
     * @param {string} value The value to uppercase. 
     */ 
     that.publicFn = function (value) { 
      return value.toUpperCase(); 
     }; 

     return that; 
    } 

    return Clazz; 
})); 

Answer 2

Miałem podobną zabawę, rozmyślając o znacznikach, aby przekonać się, że JsDoc Toolkit wypuszcza coś rozsądnego tam, gdzie rzeczy budowano dynamicznie.

Nawet jeśli I got it working, skończyło się na dziwnych dziwactwach, które wymagały ode mnie ciągłego manipulowania tagami, wyglądało to nieprzyjemnie i nadal nie zastąpiło odpowiedniej dokumentacji - równie dobrze mógłbyś czytać te komentarze w kod źródłowy.

Szczerze mówiąc, najlepszą rzeczą, jaką kiedykolwiek zrobiłem, było poświęcenie czasu na skakanie przez obręcze za pomocą JsDoc Toolkit i używanie go do write some real documentation z Sphinx.

Oprócz wrodzonych zalet każdej z przewodnikiem dokumentacji napisane przez ludzi, dla ludzi powyżej generowanych automatycznie docs API, Sfinks ma JavaScript domain directives które pozwalają udokumentować final state of the API które będą narażone na rzecz użytkowników końcowych, zamiast trochę kodu próbę aby zrozumieć sens API, przeglądając komentarze o próbach i błędach zaśmieconych swoim kodem.

Answer 3

Właściwie uważam schematy OOP Douglasa Crockforda za anty-wzorce. Nauczyłem się, jak ich nie używać. Ten artykuł podsumowuje ich wady: http://bolinfest.com/javascript/inheritance.php

Rozwiązaniem jest zapomnieć o antypodach Crockforda i nauczyć się od programistów, którzy faktycznie piszą prawdziwy kod.

Jeśli nalegać na szeregowców, proponuję używać Google Closure Compiler z jego adnotacji, jak widać tutaj: http://code.google.com/closure/compiler/docs/js-for-compiler.html

Answer 4

Znalazłem to pytanie, szukając rozwiązania tego samego problemu. W końcu znalazłem lepszy sposób rozwiązania tego problemu, jeśli nie interesuje cię dokumentowanie prywatnych metod/zmiennych (prawdopodobnie nie powinieneś, biorąc pod uwagę, że są one naprawdę zmiennymi lokalnymi i nie można uzyskać do nich dostępu z dowolnego miejsca). Wykorzystuje ona dyrektywę @alias, co jest nowego w JSDoc 3.

/** 
* @name MyModule 
* @namespace 
*/ 
define(['MyModule'], (function() { 
    "use strict"; 

    var Clazz = function (config) { 
     /** @alias MyModule.prototype */ 
     var that = {}; 

     /** 
     * Uppercases a string value. 
     * @param {string} value The value to uppercase. 
     */ 
     that.publicFn = function (value) { 
      return value.toUpperCase(); 
     }; 

     return that; 
    } 

    return Clazz; 
})); 

Answer 5

nie wiem, czy ten istniał kiedy to próbował, ale jest znacznie ładniejszy @lends użyć.

Patrz: http://usejsdoc.org/tags-lends.html

Przykład:

var Person = makeClass(
/** @lends Person.prototype */ 
{ 
    /** @constructs */ 
    initialize: function(name) { 
     this.name = name; 
    }, 
    say: function(message) { 
     return this.name + " says: " + message; 
    } 
});