.NET dilleriyle geliştirilmiş bir program sınıflardan oluşur. Sınıflar içinde de sınıf, yapı, numaralandırma, yordam gibi üyeler bulunur. İyi bir programcı, bu üyelerin kodlamasını önemsediği kadar üyelerle ilgili dokümantasyonu da önemsemelidir. Hem grup çalışmalarda bir başkasının sınıflar içindeki yapıların işlevini anlaması hem de geçmişe dönüp kodlarımızı incelediğimizde kod satırlarını daha rahat anlamak için kodlarımız arasına açıklamalar eklemeliyiz. Programlara hem tek satırlı hem de çok satırlı açıklamalar ekleyebiliriz. .NET dilleri dili açıklamalar için XML tabanlı belgelendirme formatı da sunar. Böylece hem standart bir biçim sağlanır hem de ihtiyaç duyulduğunda tüm açıklamalar XML olarak çıkarılarak msdn veya başka formatlarda etkili proje dokümantasyonu oluşturulabilir.
XML açıklamalar sınıf (class), değişken (variable), yordam (method), numaralandırma (enum), temsilci (delegate), olay (event), indisleyici (indexer) ve özellik (property) düzeyinde yapılabilir. XML açıklama, isim uzayı (namespace) için açıklama girmeyi desteklemez. Açıklama yapmak istediğimiz üyenin başına gelerek C#’ta “///” (üç tane slash) VB.NET’te ” “‘ ” (üç tane apostrof) işaretini yazdığımızda otomatik olarak o üyeye uygun XML yapısı eklenir. Bu yapı çeşitli etiketlerden oluşur. Bunların en önemlileri IntelliSense ve VS.NET “Object Browser” tarafından kullanılan
ve
Şimdi bunları bir örnekte toplayalım.
Namespace ABCYazilim
”’
namespace ABCYazilim {
///
Bunlarla birlikte XML açıklamalar içinde kullanılabilecek diğer etiketler aşağıdaki tabloda verilmiştir:
| Etiket İsmi | İşlevi |
| Üyenin nasıl kullanılacağına dair örnek göstermeye yarar. | |
|
Çok satırlı kod tanımlamak için kullanılır. |
| Sözcükleri, kodun fontuyla yazılacağını belirtir. Küçük kod parçacıkları için tercih edilir. | |
| Yordamın üretebileceği muhtemel hataları bildirir. | |
| Bullet liste, sayı liste veya tablo şeklinde maddelerin verildiği alandır. | |
| Dokümanda paragraf oluşturmak için kullanılır. | |
| Dokümanda yordam parametrelerini göstermeye yarar. | |
| Üyenin erişebilirliği hakkında bilgi verir. | |
| Doküman içinde bir metine bağlantı vermek için kullanılır. | |
| Msdn’de görmeye alıştığımız < ı>See Also bölümünde konuyla ilgili diğer alanlara yönlendirmeyi sağlar. | |
| Özellik hakkında bilgi vermek için kullanılır. |
Bu etiketleri örneğimizdeki < ı>GetBorc() yordamına uygulayalım.
”’
///
Peki, bu şekilde kodlarımızın arasına serpiştirdiğimiz açıklamaları nasıl belgelendirebiliriz. İnternet’ten bulabileceğimiz bazı araçlardan bu xml etiketlerini help dosyalarına çevirebiliriz. Bunun için tercih ettiğim araç NDoc programıydı. Özellikle açık kodlu olmasıyla ilgi çeken bu program ile msdn veya latex formatında çevrimiçi belge hazırlayabiliriz. Fakat Ndoc aracı sadece .NET 1.0 ve .NET 1.1 sürümlerini desteklemektedir. .NET 2.0 ile birlikte Ndoc (< ı>https://sourceforge.net/projects/ndoc/) geliştiricileri yeni sürüm üzerine çalışmayacaklarını ve projenin bittiğin ilan ettiler. .NET 2.0 için aşağıdaki araçlar kullanılabilir:
VS.NET üzerinden programımız içerisindeki açıklama etiketlerini bir xml dosyasına rahatlıkla çıkarabiliriz. Bunu yapmak için VS.NET’te bulunduğumuz projeyi sağ tıklayıp Properties bölümüne girelim.
C# tarafı için :
Gelen pencerenin sol tarafında Build bölümüne girerek xml dosyasının oluşmasını gerektiğini dosya adı girerek belirtebiliriz.
Aynı işlemi komut satırında da gerçekleştirebilirdik:
Csc OrnekBelge.cs /target:library /doc:OrnekBelge.xml
OrnekBelge.xml olarak belirlediğimiz dosya, derlemeden sonra programımızın bulunduğu klasörde oluşacaktır.
VB.NET tarafı için
Gelen pencerenin Compile bölümünde “< ı>Generate XML documentation file” seçeneğini işaretleyelim. Bu durumda VS.NET projeye ait projenin assembly’siyle aynı isimde bir .xml dosyası oluşturacaktır.
Aynı işlemi komut satırında da gerçekleştirebilirdik:
VBC OrnekBelge.vb /target:library /doc:OrnekBelge.xml
Fikir vermesi açısından NDoc’un eski uyarlaması üzerinden bu işlemi yapacağız. NDoc programını açıp programımızın .exe ve .xml dosyasını göstermemiz yeterli olacaktır. NDoc aracını kullanırken .xml dosya isminin assembly ile aynı olmasına dikkat etmeliyiz.
Dosyaların yolunu gösterdikten sonra “Build Documentation” butonu tıklarsak tüm ilgili dosyalar oluşacaktır. Son olarak, belirlediğimiz klasöre gidip index.html dosyasını çalıştırarak çalışmanın sonucunu görebiliriz.
Bu şekilde farklı araçlar kullanarak XML açıklamalarını HTML formata çevirebiliriz. Bu işlem esnasında bahsettiğimiz XML açıklama etiketleri aşağıdaki şekilde HTML etiketlerine dönüşür.