İçiçe Yöntemleri cevaba

Question

sayesinde tespit edildi:

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

Benim JavaScript belgelerine iyi organize ve iyi biçimlendirilmiş olduğunu. Her ad alanı, içinde yer alan yöntemlerin "üst öğesi" dir. Ancak, navigasyon istediğim kadar ayrıntılı değildir.

node.js aracını kullanarak basit bir komut (jsdoc file1.js file2.js) kullanarak derledikten/oluşturduktan sonra, dokümanlar varsayılan bir şablona oluşturulur. Bu varsayılan şablon, kenar boşluklarımdaki yön alanlarını görüntüler, ancak her birinin içerdiği yöntemleri göstermez.

yapabilirsiniz sahte her yönteme @class direktifini ekleyerek, ama bildiğimiz gibi, gerçekten sınıflar değildir tarafından yöntemlerinin listesi.

Böyle bir kenar çubuğu navigasyon görmek isterdim:

My Project 

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

-namespace 2 
    - method.d 
    - method.e 

ben büyük takdir gözardı belgelere Herhangi yönü.

---

[değiştir eklemek için:] deney üzerine

, @class neredeyse tam ne istiyorum ama bazı istisnalar dışında kapsamaz:

• Bu ad yukarıdaki sınıflar listeler. İsim alanlarının "ebeveyn" olduğu için bundan hoşlanmıyorum.

• JavaScript'in bu anlamda sınıfları yok. Bu isimlendirmeyle "sınıflar" olarak adlandırılanlar değil. "Sınıflar" listesini görmek için belgeyi okurken garip bir kopukluk oluşturur.

• "Yeni" operatörü otomatik olarak ekler. Tüm yöntemlerin kurucuları yok ... sorunu görebiliyorsunuz!

---

[değiştir: örnek kod]

Yani burada mevcut yapımız var. Ben JSDoc yorumlarla kendi açıklamalarını önce burada temel yaklaşım var:

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

Yani, nesne değişmezi gösterimi kullanarak, üst seviye, bütün uygulama için "ad", ancak farklı amaçlar için alt ad vardır içinde . Burada, yardımcı programlara özgü bir alt isim-alanı ve işleme için özel bir tane var. Her birinin özellikleri olabilir, ancak daha önemlisi her biri işlevleri içerir. Kenar çubuğunda görünmesi gereken bu işlevlerdir. Şimdi JSDoc için benim şimdiki desenle eti dışarı:

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

Eğer @lends etiketini kullanarak denediniz mi? Kodunuzun ve doküman yorumlarınızın bir örneği burada yardımcı olabilir.

Kodunuzun neye benzediğini bilmediğimden, JSDoc'u nasıl kullanabileceğimin bir örneğini vereceğim. Sadece kullanmalıyım).

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

Biz kullanan omurga için bir bağımlılık enjeksiyon sistemine sahip:

Sadece bazı içerik sağlamak için biz uygulamalar ve modülleri (uygulamalar sadece start yöntemiyle modülleri vardır) oluşturabileceğiniz bir context nesne var ifade eden bağımlılıkları için açısal tarzı desen:

/** 
* 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 
]); 

Ve sonra farklı bir dosya myModelName örneğidir altındaki o bağımlılık dizisine ekleyerek enjekte olabilir.

tuhaf yönü JSDoc aslında yaptığı gibi uzun ben de süslenmeye çalışma yok gibi, söz konusu düzenleme anlamak ... ama şu desen bunun için görünüşte çok kafa karıştırıcı oldukça iyi bir iştir:

/** 
* @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 
]); 

İstediğim çıktıya yakın bir şey veren bulduğum tek şey, JSDoc'a belirli bir nesne/özellik/yöntemin farklı bir özellik olarak "ödünç verildiğini" bildirmek için @lends etiketini kullanmasıdır. Örneğin, (görünüşte onun defaults özelliği ile tanımlanır) bir omurga modelinin attributes özelliğini belgelemek için, bunu:

MyApp.MyModel.prototype = { 

    idAttribute: 'customId', 

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

}; 

Ve bu durum için

nerede hizmet bir nesne dönüyor, tek yolu belgelenmiş olanlar nesne özelliklerini almak için bulduk ettik şu şekildedir:

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

}; 

hiçbirini faydalı oldu hiçbir fikrim yok, ama belki size @lends ile deneyebilirsiniz şeyler için bazı fikirler vereceğiz. Bazı örnek kodlar sağlayabiliyorsanız, size daha yararlı bir yanıt verebilirim.