Javadocs'ta kod örnekleri nasıl güncel tutulur


9

Temel, iyi bilinen dize metriklerinin uygulamalarını sağlayan küçük bir kütüphane üzerinde çalışıyorum. Çoğunlukla kendi eğitimim için. Yani biraz boş zamanım olduğunda gelişme olur.

Bu nedenle, çoğu işlemi otomatikleştirdim, böylece çok fazla çaba harcamadan çalıştığım kadar sık ​​bir sürüm yayınlayabilirim. Bununla birlikte, Java belgesini korumak hala bir yüktür çünkü örnekler içerir.

API geliştikçe her örneği tekrar tekrar kontrol etmem gerekiyor. Bunu yapmanın daha iyi bir yolu var mı?

Belgeleri ve örnekleri ayrı bir projeye (örn. Kaliper Eğitimi ) taşımayı düşündüm, böylece normal faktörle birlikte yeniden faktörlü ve derlenebilir. Ancak bu, dokümanları ilgili sınıftan uzaklaştırır.

Yani evet. Pastanı alıp da yemek istiyorum. : D

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

Yukarıdaki çok soyut ise. Bu bir dokümantasyon örneğidir. Şu anda Tokenizers.createQGram(2), yapıcı yöntemini amortismana tabi tutarken , Etkili Java tarafından önerilen statik yapıcıları ekliyorum . Böyle bir şey yaptığımda, yukarıdaki örnek kodu güncellemem ve hala çalışıp çalışmadığını kontrol etmeliyim.

Yanıtlar:


8

Bu soruya cevap vermeyebilir - belgelerinizde bu örneklere sahip olmanın ne kadar 'gereksinim' olduğuna bağlı olarak.

Belki farklı bir açı yapabilirsiniz: JUnit testlerinize örnekler verin. (Belki de com.examples gibi bir paket bile) Yorumlardaki kodla ilgili sorun, IDE'nizin çoğunlukla görmezden gelmesidir. Ancak IDE'niz JUnit testlerinizdeki kodu doğrulayacaktır. Bunu yaparak, kod örneklerinin 'doğru' olduğundan emin olursunuz - testler derlenmez veya güncellemediyseniz başarısız olur.

Javadocs ile bir sihirbaz değilim, ancak kaynak dosyanızın belgelerini JUnit dosyasına örnek kodla bağlamanın bir yolu olabilir. Buna rağmen nereden başlayacağımı gerçekten bilmiyordum. Bir cursory googling bana @seeetiketi gösterdi . Bir projede test ettim ama üretildikten sonra gerçek bir javadocta test etmedim.

Bu kesinlikle ön araştırma biraz gerektirir, ama gerçekten kod örnekleri gerçekten derlenmiş olsaydı uzun vadede daha iyi olacağını düşünüyorum.

Uzatma hedefi olarak, JUnit örneklerinizi çalıştırırken kod kapsamı da ekleyebilirsiniz. Bu şekilde, bir bakışta kod tabanınızın ne kadarının örnekleriniz tarafından kapsanacağını bir bakışta bilirsiniz.


Birim test yeteneği beni ikna etti. Belgeleri basit bir işlevsel açıklamaya ayıracağım ve örnekleri bir öğretici projeye taşıyacağım. Github'daki bir dosyaya bağlantı vermek biraz garip olabilir, ancak bu kabul edilebilir bir işlemdir.
MP Korstanje
Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.