Soru JSDoc ile CoffeeScript kaynak kodu nasıl belgelenir?


CoffeeScript'te yazılmış bir kodum var ve oluşturulan JavaScript'i Google Closure Compiler ile optimize etmek istiyorum, bu yüzden bu dosyaların JSDoc ile belgelenmesi gerekiyor.

Benim sorum, kapama derleyicisi için çalışan JSDoc içeren javascript oluşturmak için * .coffee dosyalarını nasıl belgeleyebilirim?

Bir soru daha var: * .coffee'de tek satırlık bir yorumu saklamanın bir yolu var mı?


44
2017-10-20 08:23


Menşei


Lütfen sorunuza yönelik bir cevap seçin: Kapatma derleyicisi için çalışan JSDoc içeren javascript oluşturmak için * .coffee dosyalarını nasıl belgeleyebilirim? - Patrick McLaren


Cevaplar:


Buna karşı tavsiye ederim. Tüm kodunuzu JSDoc-ing, Closure Compiler'dan çok az fayda sağlayamayacak kadar zorlu bir süreçtir. Google’ın dışında hiç kimse bunu yapmıyor. CoffeeScripters / JavaScripters genellikle, docco.

Ayrıca, Closure Compiler onun arkasında Google marka adı bulunurken, UglifyJS Birçok durumda daha verimli minifikasyon aracı olduğu kanıtlanmıştır. (jQuery kısa süre önce değiştirildi ona.)

Bir soru daha var: * .coffee'de tek satırlık bir yorumu saklamanın bir yolu var mı?

Evet:

### foo ###

veya

`// foo`

4
2017-10-20 15:02



Gelişmiş modda kullanıldığında, google kapatma derleyicisi eşsiz sıkıştırma ve yürütme hızı sağlar. Adresindeki ölçütlere bakın jsperf.com/testing-code-performance-by-compression-type - Aleš Kotnik
JSDoc'a, Closure Compiler optimizasyonunun ötesine geçen, harika görünümlü derlenmiş dokümantasyon yapmaktan çok daha önemli olan birçok faydası vardır. JSDoc kullanıyorsanız, iyi bir IDE, ipucu verebilir ve yazabilir, uyarılar / hatalar verebilir ve @ see / @ bağlantısını gezinebilir yapabilir. Sayısız hataların kökü düşünüldüğünde ya imza eksikliği ya da ona bağlılık eksikliği, JSDoc'un herhangi bir JS'de minimize edildiğini veya minimuma indirildiğini iddia ediyorum (ve aynı zamanda CoffeeScript bağlamında mutlu bir şekilde sindiren PHPStorm gibi bazı IDE'ler de var) . - Ezekiel Victor
Ayrıca, çok fazla kontrendike olmamakla birlikte, docco'nun "hafif dokümantasyonda" dediğiniz gibi nasıl? Üçüncü taraf bileşenlerini, ek yapılandırmayı, yapı rutininize eklenen başka bir derleme yordamını ve geliştiricinin orijinal kaynak kodu bağlamında işlevsel olmayan güzel, büyük şişkin yorumların üretilmesi için tüm ekstra ilginin en kötüsünü gerektirir (bkz. JSDoc). yukarıdaki argümanlar). - Ezekiel Victor
Bu 'cevap' soruyu kişisel görüş lehine reddeder. - rath
-1 bu sorunun cevabı değil - Nuno Costa


CoffeeScript Girişi:

### define function variable before block to avoid code being appended to closing part of JSDoc comment ###
cube = null

###*
 * Function to calculate cube of input
 * @param {number} Number to operate on
 * @return {number} Cube of input
 ###

cube = (x) -> x*x*x

Windows cmd'den JavaScript Çıktısı istemek için: coffee -cpb src.coffee

// Generated by CoffeeScript 1.6.3
/* define function variable before block to avoid code being appended to closing part of JSDoc comment*/

var cube;

cube = null;

/**
 * Function to calculate cube of input
 * @param {number} Number to operate on
 * @return {number} Cube of input
*/

cube = function(x) {
  return x * x * x;
};

Düzenle

Ayrıntılı olarak diğer cevap CoffeeScript 1.7.1, bu sorunu çözmek için daha iyi bir yönteme sahiptir.


75
2018-02-06 08:12



Not: Coffeescript derleyicisi, yorumlamadan sonra whitespaces ekler, bu nedenle, bazı ayrıştırıcılar JSDoc olarak tanımayabilir, yani, (başka bir belge ile deneyiminden), yöntem tanımlaması başlamadan önce tam olarak satır olması gerekiyor - SirLenz0rlot
Bu artık işe yaramıyor. CoffeeScript 1.6.3 ile JavaScript çıktısı bir var cube JSDoc 3.2.0 işlevini belgeleyecek şekilde engelleyen işlev tanımından önce. - rvernica
Hala benim için çalışıyor, yanıtlamak için güncellemeye bakın ... - Billy Moon
Bunu söylemiştim, JSDoc 3.2.0'ı denemedim - bu gerçekten işe yaramayabilir, çünkü benim yöntemimin amacı değişkeni bloktan önce tanımlamaktır. - Billy Moon
"Tüm kodunuzu JSDoc-ing, Closure Compiler'dan hiçbir fayda elde etmek için çok az faydası olan zahmetli bir süreçtir". Daha fazla katılıyorum. Ve ortaya çıkan çıktının sonuçta hiçbir faydaya yakın olmayan geçerli bir JSDoc formatı vereceğini umarak Pseudo-JSDoc-ing CoffeeScript kodu. Bazı sürümlerle iyi çalışabilir. Fakat "mayıs", çabaya değmez. - Lukas Bünger


Doğrudan yukarıdaki Billy'ye yanıt veremediğimden, bunun için daha iyi bir destek olan CoffeeScript 1.7.1 görünüyor:

###*
# Sets the language and redraws the UI.
# @param {object} data Object with `language` property
# @param {string} data.language Language code
###

handleLanguageSet: (data) ->

çıktılar

/**
 * Sets the language and redraws the UI.
 * @param {object} data Object with `language` property
 * @param {string} data.language Language code
 */
handleLanguageSet: function(data) {}

33
2018-06-22 07:02





Denemelisiniz (çok), ama ### yorum arkadaşın.

Kahve-script derleyici kullanmak ### formu (dokümanlar İşte).

Gerçekten basit bir şekilde yaratmaya çalıştım JsDoc Sitede 'coffeescript' özelliğini kullanarak bir işlev için parça:

###* Doc for this function.###
foo = -> 'bar'

Bu verdi:

/** Doc for this function.
*/
var foo;
foo = function() {
   return 'bar';
 };

Uzman değilim JsDocama tahmin ediyorum var foo; fonksiyonun üstündeki ifade bir sorun yaratacaktır. Olsaydı foo daha önce ilan edilmiş, maybee ..

Nasıl gittiğini anlamak güzel olurdu.


6
2017-10-20 14:59





class bir problem var

###* this is a class ###
class hello
    v: 4

bunu verir

// Generated by CoffeeScript 2.0.0-beta5
/** this is a class */
var hello;

hello = (function() {
  class hello {};

  hello.prototype.v = 4;

  return hello;

})();

ve JSDoc'ta geçersiz


0
2017-09-08 12:29