C ++: Doxygen ile belgeler oluşturma - AYDINLATMALAR

Çoğu programcı, kendi kodunu yorumlamaktan nefret ettikleri kadar belgeler yaratmaktan nefret eder. Doxygen'i girin; bu, programcıların, daha sonra dokümantasyon oluşturmak için çıkarılan yorumlara katıştırmalarını sağlar.

Doxygen

yükleme Doxygen Code:: Block'larla birlikte gelmez (en azından bu yazı itibariyle). Uygulamanız için Doxygen'in uygun sürümünü indirmeniz gerekecek. (Kod:: Blocks sitesinden Doxygen web sitesine bir bağlantı var.) Doxygenorg web sitesine bağlandıktan sonra, indirme sayfasına gidin ve burada gösterildiği gibi işletim sisteminiz için Doxygen sürümünü bulun:

İşletim sisteminize uygun olan sürümünü indirin ve yükleyin. Varsayılanları kabul edebilirsiniz, ancak kurulum sihirbazının Doxygen çalıştırılabilir dosyasını nereye koyduğunu unutmayın.

Şimdi Kodu Başlat:: Bloklar. DoxyBlocks → Tercihleri ​​Aç'ı seçin. Buradan General (Genel) sekmesini seçin ve Doxygen Yolunu ayarlayın. (Bu, önceki paragrafta not ettiğiniz yoludur.) Windows için varsayılan yol C: Program Filesdoxygenbindoxygen'dir. exe. Aynı şeyi Doxywizard Yolu için de yapın. Burada Windows için varsayılan değer C: Program Filesdoxygenbindoxywizard'dır. exe . HTML formatında dokümantasyon üretirken ihtiyaç duyulmadığı için diğer araçları boş bırakabilirsiniz.

Belgelendirme Ekleme Yorumları

Doxygen, aracın belgeler oluşturmasına yardımcı olan anahtar kelimeleri işaretlemek için özel yorumlar kullanır. Kafa karıştırıcı bir şekilde, Doxygen birçok farklı standart kabul eder, ancak varsayılan JavaDoc'a en çok benzeyen, / ** yorumu iyi bir değerdir. (DoxyBlocks → Tercihleri ​​Aç'ı seçip ardından Yorum Stili sekmesini seçerek yorum stilini diğerlerinden birine değiştirebilirsiniz.)

Bunun nasıl çalıştığını görmek için imleci bir işlevin başına getirin ve DoxyBlocks → Block Comment'i seçin (veya Ctrl + Alt + B tuşlarına basın). Aşağıdaki gibi bir açıklama görüntülenir (aşağıdaki örnekler www.dummies. Com / extras / cplusplus adresindeki indirilebilir materyalde yer alan Budget5 programını kullanmaktadır):

/ ** brief * * param accList list & * return void * * / void getAccounts (liste ve accList) {

Kod:: Bloklar, / ** ile başlayan bir Doxygen blok yorumu ekler. Doxygen, bu açıklamanın hemen ardından gelen işlev tanımına ait olduğunu bilir. Doxygen anahtar kelimeleri bir (ters eğik çizgi) ile başlar. kısa anahtar kelimesi işlevin kısa açıklamasını işaretler. Kısa açıklama birden fazla satırı aşabilir.Bu, tablo görüntülerinde görünen işlevin kısa bir açıklaması olmalıdır.

Programcı bunu ayrıntılar anahtar kelimesi ile işaretlenmiş daha ayrıntılı bir açıklama ile takip edebilir. Bu ayrıntılı açıklama, işlevin ne yaptığının daha kapsamlı bir açıklaması sağlar.

Doxygen anahtar kelimelerinin çoğu isteğe bağlıdır. Özellikle, kısa açıklamasından bir paragrafı boş bir satırdan daha fazla başlayarak başlatırsanız, ayrıntılar anahtar kelimesi varsayılır.

Bunun ötesinde, işlevin her bağımsız değişkenini tanımlamak için param anahtar sözcüğü ile işaretlenmiş ayrı bir satır var. Son olarak return anahtar kelimesi, işlev tarafından döndürülen değeri açıklar.

doldurulduğunda getAccounts () için Doxygen yorumu aşağıdaki gibi görünebilir:

/ ** kısa getAccounts - klavyeden hesap girişi * details Bu işlev klavyeden girdi okur. * Girilen her S veya C için, fonksiyon yeni * Tasarruf veya Kontrol eden hesap nesnesi oluşturur ve * hesap listesine ekler. Bir X, girişi sonlandırır. Diğer * girdilerin depozitosu (* 0'dan büyük sayılar) veya para çekme (0'dan küçük sayılar) olduğu varsayılır. * * param accList listesi ve getAccounts () tarafından oluşturulan hesap * nesneleri listesi * return void * / void getAccounts (liste ve accList) {

Aynı satırda bir Doxygen yorumu da ekleyebilirsiniz. Bu, çoğunlukla veri üyelerine yorum yaparken kullanılır. İmleci satırın sonuna getirin ve DoxyBlocks → Line Comment'i seçin veya Ctrl + Alt + L tuşlarına basın. Şimdi veri üyesinin bir açıklaması doldurun. Sonuç aşağıdaki örnekte olduğu gibi yine Budget5'den alınmış gibi görünür:

çift denge; / ** 

Doxygen belgelerinin üretilmesi
Doxygen belgeleri farklı biçimlerde üretebilir, ancak bazıları (derlenmiş HTML gibi) daha fazla indirmeye ihtiyaç duymaktadır. HTML biçimi, görüntülemek için bir tarayıcıdan başka bir şey gerektirmediğinden özellikle uygundur.
Varsayılan HTML, ancak formatı değiştirmek isterseniz DoxyBlocks → Açık Tercihler'i seçin, sonra Doxyfile Defaults 2 sekmesini seçin. Bu pencerede, oluşturmak istediğiniz tüm farklı formatları seçebilirsiniz.
Belgeleri ilk defa ayıklamadan önce, muhtemelen birkaç başka seçenek seçmek isteyeceksiniz. DoxyBlocks → Açık Tercihler'i seçin ve Doxyfile Defaults sekmesini seçin. Tümünü Çıkar kutusunun işaretli olduğundan emin olun. Sonra Doxyfile Defaults 2 sekmesini seçin ve Class_Diagrams onay kutusunu işaretleyin. Şimdi Genel sekmesini seçin ve Derlemeden Sonra HTML'yi Çalıştır kutusunu işaretleyin. Tamam'ı tıkladığınızda işlemi tamamladınız. (Seçenekler doxyfile adlı bir dosyaya kaydedildiğinden bunu bir daha yapmak zorunda kalmazsınız.)
Belgeleri oluşturmak ve görüntülemek için DoxyBlocks → Belgeyi Çıkar'ı seçin. Oldukça kısa bir süre sonra, Doxygen, aşağıdaki şekilde gösterildiği gibi belgelerle favori tarayıcınızı açar.
Doxygen, girdi hataları söz konusu olduğunda pek kullanıcı dostu değildir. Bazen Doxygen, belirgin bir sebep olmadan kaynağınızdaki bir noktada dokümantasyon üretmeyi durdurur.Doxyjeni kontrol et. Çıkarma sırasında oluşabilecek hatalar için doxyfile ile aynı dizinde bulunan günlük dosyası.
Aşağıdaki resim, kullanıcının proje belgelerinde gezinmesini sağlayan proje tarayıcısını sol pencerede gösterir. Sağda, daha ayrıntılı bir açıklama elde etmek için getAccounts () işlevi seçildi. Kısa açıklama ilk satırda, ardından ayrıntılı açıklama, parametreler ve dönüş değeri görüntülenir:

Sınıf dokümantasyonu, aşağıdaki kod snippet'inde gösterildiği gibi tamamen kapsamlıdır.
/ ** class Account * kısa soyut bir banka hesabı. * ayrıntılar Bu soyut sınıf her iki hesap türüne de özel * mülkleri içermektedir: * Denetleme ve Tasarruf. Bununla birlikte, iki * / sınıf Hesabı {

 Hesap için dokümantasyon arasında gösterilen * kavramı geri çekme (), eksiktir burada gösterilmektedir:

sınıf Hesap . Bu kısa açıklama. Diğer öğesini tıklamak sizi ayrıntılı açıklamaya götürür. Ayrıca, Hesap , ana sınıfları ve çocuk sınıfları arasındaki devralma ilişkisinin grafik gösterimini görürsünüz.