metodi nidificati in barra laterale di JSDoc

Question

Grazie alla risposta trovato qui:

https://stackoverflow.com/a/19336366/592495

documentazione mio JavaScript è ben organizzato e ben formattato-. Ogni spazio dei nomi è un "genitore" dei metodi contenuti all'interno. Tuttavia, la navigazione non è così dettagliata come vorrei.

Dopo la compilazione/rendering utilizzando lo strumento node.js tramite un semplice comando (jsdoc file1.js file2.js), i documenti vengono generati in un modello predefinito. Questo modello predefinito visualizza i miei spazi dei nomi nella barra laterale di navigazione, ma NON mostra i metodi che ciascuno contiene.

È possibile simulare un elenco di metodi aggiungendo la direttiva @class a ciascun metodo, ma come sappiamo, non sono realmente classi.

Mi piacerebbe vedere una barra laterale di navigazione come questa:

My Project 

- namespace 1 
    - method.a 
    - method.b 
    - method.c 

-namespace 2 
    - method.d 
    - method.e 

qualsiasi direzione per la documentazione ho trascurato sarebbe molto apprezzato.

---

[Modifica per aggiungere:]

Al momento la sperimentazione, @class fa quasi esattamente quello che voglio, ma con alcune eccezioni:

• elenca le classi sopra namespace. Non mi piace perché gli spazi dei nomi sono i "genitori" per così dire.

• JavaScript non ha classi in questo senso. Non quelli che sono chiamati "classi" con quella nomenclatura. Crea una strana disconnessione durante la lettura del documento per visualizzare un elenco di "classi".

• Aggiunge automaticamente il "nuovo" operatore. Non tutti i metodi hanno costruttori ... puoi vedere il problema!

---

[edit: codice di esempio]

Quindi, ecco l'attuale struttura. Prima di annotare con commenti JSDoc, ecco l'approccio di base:

var app = app || {}; 
app.utils = { 
    whizbang: function() {}, 
    geegolly: function() {} 
    }; 
app.render = { 
    thestuff: function(params) {}, 
    thethings: function(params) {} 
    } 
} 

Quindi, utilizzando oggetto la notazione letterale, il livello superiore è un "namespace" per l'intera applicazione, ma all'interno ci sono sotto-namespace per scopi diversi . Qui, ho uno spazio secondario specifico per le utilità e un altro specifico per il rendering. Ognuno può avere proprietà, ma, soprattutto, contengono ciascuna funzioni. Sono queste funzioni che dovrebbero apparire nella barra laterale. Ora per la carne fuori con il mio attuale modello per JSDoc:

/** 
* @file MyApp.js This is an awesome description of MyApp.js 
* 
* @version 0.1 
* @author Greg Pettit 
* @copyright 2015 
* 
*/ 

/** 
* Description of my main namespace! 
* 
* @namespace app 
*/ 
var app = app || {}; 

/** 
* This is a description of my sweet utilities namespace! 
*                    
* @memberof app 
* @type {object} 
* @namespace app.utils 
*/ 
app.utils = { 
    /** 
    * app.utils.whizbang is an awesome function with magical powers. I sure wish 
    * it would appear in the sidebar as a member of app.utils! 
    * 
    * @memberof app.utils 
    * @method whizbang 
    * 
    * @param {method} [successCallback] Method invoked on successful attempt. 
    * @param {method} [errorCallback] Method invoked on unsuccessful attempt. 
    * 
    */ 
    whizbang: function(successCallback, errorCallback) { // do utility stuff! } 
} 

/** 
* This is a description of the best rendering namespace ever. 
*                    
* @memberof app 
* @type {object} 
* @namespace app.render 
*/ 
app.render = { 
    /** 
    * app.render.thethings renders the things! I wish it would render to the sidebar... 
    * 
    * @memberof app.render 
    * @method thethings 
    * 
    * @param {method} node The node to which thethings are rendered 
    * 
    */ 
    thethings: function(node) { // do rendering stuff! } 
} 

Answer 1

Hai provato a usare il tag @lends? Un esempio del tuo codice e dei commenti del doc sarebbe utile qui.

Dal momento che non so come sia il tuo codice, darò solo un esempio di come utilizzo JSDoc con il nostro framework interno, che ha molte idiosincrasie (hey, non l'ho scritto, Devo solo usarlo).

solo per dare un po 'di contesto, abbiamo un oggetto context in grado di creare applicazioni e moduli (applicazioni sono solo moduli con un metodo start):

/** @namespace MyApp */ 
var MyApp = context.app('myApp').use('module1', 'module2', 'underscore'); 

Abbiamo un sistema di iniezione di dipendenza per la spina dorsale che utilizza un Reticolo angolare stile per dipendenze esprimono:

/** 
* The constructor for MyModel 
* @memberof MyApp 
* @param {object?} attrs 
* @param {object?} options 
* @param {AppUtils} appUtils 
* @constructor 
*/ 
MyApp.MyModel = function(attrs, options, appUtils) { 
    this.options = options; 
    this.utils = appUtils; 
} 

// This is injected by the dependency resolver at instantiation time 
// No additional JSDoc comments are necessary, it actually gets this right 
MyApp.MyModel.prototype = { 

    idAttribute: 'customId', 

    defaults: { 
     customId: '', 
     name: '', 
     birthday: null 
    } 

}; 

// Registers MyModel with the IOC container as 'myModelName' 
MyApp.model('myModelName', [ 
    'attrs', 
    'options', 
    'appUtils' 
    MyApp.MyModel 
]); 

E poi un altro file può avere un'istanza di myModelName iniettato aggiungendolo a quella matrice dipendere in basso.

La cosa divertente è, JSDoc in realtà fa un buon lavoro di comprendere quel particolare disposizione, finché io non cerco di ottenere troppo di fantasia ... ma il seguente schema è apparentemente troppo confusa per esso:

/** 
* @memberof MyApp 
* @param {MyApp.MyModel} myModel 
* @param {urlParser} urlParser 
* @constructor 
*/ 
MyApp.SomeService = function(myModel, urlParser) { 

    return { 

     foo: function() { 
      //whatever 
     }, 

     bar: function() { 
      //whatever 
     } 

    }; 

}; 

MyApp.service('someModuleName', [ 
    'myModelName', 
    'urlParser', 
    MyApp.SomeService 
]); 

L'unica cosa che ho trovato che mi dà qualcosa di simile all'output desiderato è usare il tag @lends per dire a JSDoc che un particolare oggetto/proprietà/metodo è "prestato" come una proprietà diversa. Ad esempio, per documentare la proprietà attributes di un modello dorsale (che è apparentemente definita dalla sua proprietà defaults), facciamo questo:

MyApp.MyModel.prototype = { 

    idAttribute: 'customId', 

    /** @lends MyApp.MyModel.prototype.attributes */ 
    defaults: { 
     customId: '', 
     name: '', 
     birthday: null 
    } 

}; 

E per questo caso in cui il servizio restituisce un oggetto, l'unico modo per 'ho trovato per ottenere quelle proprietà degli oggetti documentati è come questo:

/** 
* @memberof MyApp 
* @param {MyApp.MyModel} myModel 
* @param {urlParser} urlParser 
* @constructor 
*/ 
MyApp.SomeService = function(myModel, urlParser) { 

    /** @lends MyApp.SomeService.prototype */ 
    return { 

     foo: function() { 
      //whatever 
     }, 

     bar: function() { 
      //whatever 
     } 
    }; 

}; 

non ho idea se nulla di tutto ciò è stato utile, ma forse ti do alcune idee per cose che si potrebbe provare con @lends. Se puoi fornire qualche codice di esempio, posso darti una risposta più utile.