Bir dahili kitaplık için doxygen yorum blokları nereye yerleştirilir - H veya CPP dosyalarında? [kapalı]

Sağduyu, Doxygen yorum bloklarının, sınıfların, yapıların, numaralandırmaların, işlevlerin, bildirimlerin olduğu başlık dosyalarına yerleştirilmesi gerektiğini söyler. Bunun, kaynağı olmadan dağıtılması gereken kütüphaneler için sağlam bir argüman olduğunu kabul ediyorum (yalnızca nesne kodlu başlıklar ve kitaplıklar).

AMA ... Tam kaynak koduyla kullanılacak bir şirket içi (veya kendim için bir yan proje olarak) kitaplık geliştirirken tam tersi bir yaklaşımı düşünüyordum. Önerdiğim şey, başlıkta bildirilen sınıfların ve işlevlerin arayüzünü karıştırmamak için uygulama dosyalarına (HPP, INL, CPP, vb.) Büyük yorum bloklarını koymaktır.

Artıları:

• Başlık dosyalarında daha az dağınıklık, yalnızca işlevlerin sınıflandırılması eklenebilir.
• Örneğin Intellisense kullanıldığında önizlenen yorum blokları çakışmaz - bu .H dosyasındaki bir işlev için bir yorum bloğuna sahip olduğumda ve aynı .H dosyasında satır içi tanımına sahip olduğumda gözlemlediğim bir kusurdur. ancak .INL dosyasından dahil edilmiştir.

Eksileri:

• (Açık olanı) Yorum blokları, bildirimlerin bulunduğu başlık dosyalarında değildir.

Öyleyse, ne düşünüyorsunuz ve muhtemelen öneriyorsunuz?

Belgeleri, insanların kodu kullanırken ve üzerinde çalışırken okuyacağı ve yazacağı bir yere koyun.

Sınıf yorumları sınıfların önüne, yöntem açıklamaları yöntemlerin önüne geçer.

İşlerin bakımının yapıldığından emin olmanın en iyi yolu budur. Ayrıca üstbilgi dosyalarınızı görece zayıf tutar ve kişilerin yöntem belgelerini güncelleyerek başlıkların kirlenmesine ve yeniden oluşturmaları tetiklemesine neden olan dokunma sorununu önler . Aslında insanların bunu daha sonra belge yazmak için bir bahane olarak kullandıklarını biliyorum !

İsimlerin birden çok yerde belgelenebilmesi gerçeğinden yararlanmayı seviyorum.

Başlık dosyasına, yöntemin kısa bir açıklamasını yazıyorum ve tüm parametrelerini belgeliyorum - bunların, yöntemin kendisinin uygulanmasından daha az değişme olasılığı daha düşüktür ve eğer değiştirirlerse, o zaman işlev prototipinin her durumda değiştirilmesi gerekir. .

Uzun formatlı dokümantasyonu kaynak dosyalara gerçek uygulamanın yanına koydum, böylece yöntem geliştikçe ayrıntılar değiştirilebilir.

Örneğin:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Başlıkta yorumların olması, bir yorum değiştirilirse bir sınıfın tüm kullanıcılarının yeniden derlenmesi gerektiği anlamına gelir. Büyük projeler için kodlayıcılar, önümüzdeki 20 dakikayı her şeyi yeniden inşa etmek için harcama riski varsa, başlıklardaki yorumları güncellemeye daha az meyilli olacaklar.

Ve .. html belgesini okumanız ve dokümantasyon koduna göz atmanız gerekmediğinden, yorum bloklarının kaynak dosyalarda bulunmasının daha zor olması büyük bir sorun değildir.

Başlıklar: Dosyalara bakarken daha az başka "gürültü" olduğu için yorumları okumak daha kolaydır.

Kaynak: O halde yorumlara bakarken okuyabileceğiniz gerçek işlevlere sahipsiniz.

Biz sadece başlıklarda açıklanan tüm genel işlevleri ve kaynakta açıklanan yerel işlevleri kullanıyoruz. İsterseniz, belgeleri birkaç kez yazmak zorunda kalmadan birden çok yere eklemek için copydoc komutunu da dahil edebilirsiniz (bakım için daha iyidir)

Bununla birlikte, sonuçları basit bir komutla farklı dosya belgelerine kopyalayabilirsiniz. Örneğin :-

Benim dosyam1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

Benim dosyam1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Artık her iki işlev için de aynı dokümantasyonu alıyorsunuz.

Bu, kod dosyalarında size daha az gürültü verirken, aynı zamanda son çıktıda birkaç yerde sunulan belgeleri tek bir yerde alırsınız.

Genellikle .h dosyasına arabirim (\ param, \ return) için belgeleri ve .c / .cpp / .m dosyasına uygulama için belgeleri (\ details) koyarım. Doxygen, fonksiyon / yöntem dokümantasyonundaki her şeyi gruplar.

Her şeyi başlık dosyasına koydum.

Her şeyi belgeliyorum, ancak yalnızca genel arayüzü çıkarıyorum.

Programlama için QtCreator kullanıyorum. Çok kullanışlı bir numara, beyanı başlık dosyasında almak için bir işleve veya yönteme Ctrl-Tıklamadan oluşur.

Yöntem başlık dosyasında yorumlandığında, aradığınız bilgiyi hızlı bir şekilde bulabilirsiniz. Bu yüzden benim için yorumlar başlık dosyasında bulunmalıdır!

C ++ 'da bazen uygulama başlık ve .cpp modülleri arasında bölünebilir. Burada, dokümantasyonu başlık dosyasına koymak daha temiz görünüyor, çünkü burası tüm genel işlevlerin ve yöntemlerin garanti edildiği tek yerdir.