Obtener los patrones de diseño de jsdoc y Crockford para llevar bien

Question

Estoy usando Douglas Crockford's design pattern para implementar métodos privados, privilegiados y públicos. Básicamente se ve algo como esto (usando RequireJS):

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

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

     _privateFn = function() { 
      return 42; 
     }; 

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

     _init(arguments); 

     return that; 
    }; 
}); 

Sin embargo, estoy teniendo problemas para conseguir la jsdoc toolkit para analizar correctamente. He jugado con las anotaciones @name y @memberOf (como here), pero haga lo que haga, no puedo hacer que aparezcan las funciones.

¿Alguien sabe una solución?

Answer 1

bien, finalmente lo he descubierto. Así es como lo hace:

/** 
* @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

He tenido la misma diversión jugando con las etiquetas para tratar de obtener JsDoc Toolkit para producir algo sensato donde las cosas se construyen de forma dinámica.

Incluso cuando I got it working, terminó con caprichos extraños que me obligaban a jugar con las etiquetas una y otra vez, parecía poco atractivo y aún no era un sustituto de la documentación adecuada. También podría leer esos comentarios en el código fuente.

Honestamente, lo mejor que he hecho fue tomarme el tiempo que estaba pasando saltándome los aros con JsDoc Toolkit y usarlo en write some real documentation con Sphinx.

Además de los beneficios inherentes de cualquier documentación guiada por escrito por personas para personas mayores de documentos de la API generados automáticamente, Sphinx tiene JavaScript domain directives que le permiten documentar la final state of the API que será expuesto a los usuarios finales, en lugar de tener algún intento de código para darle sentido a la API observando los comentarios de prueba y error que se encuentran en su código.

Answer 3

En realidad considero los patrones OOP de Douglas Crockford como antipatrones. Aprendí la manera difícil de no usarlos. Este artículo resume sus inconvenientes: http://bolinfest.com/javascript/inheritance.php

Así que la solución es olvidarse de los antipatrones de Crockford y aprender de los desarrolladores, que realmente escriben códigos reales.

Si insiste en soldados, sugiero que uses Google Closure Compiler con sus anotaciones, como se puede ver aquí: http://code.google.com/closure/compiler/docs/js-for-compiler.html

Answer 4

He encontrado esta pregunta al buscar una solución al mismo problema. Terminé encontrando una mejor manera de resolver esto si no te importa documentar métodos/variables privados (que probablemente no deberías, ya que son variables locales y no se puede acceder desde ningún otro lugar). Se utiliza la directiva @alias, que es nuevo en 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

No sabe si esto existía cuando lo intentó, pero @lends es significativamente más agradable de usar.

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

Ejemplo:

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