Joshua's Blog

Dokumentasi source code mungkin untuk sebagian teman-teman belum menjadi prioritas dalam bekerja. Apalagi jika kita merupakan seorang single fighter atau hanya terdiri dari tim yang kecil. Namun, dengan penerapan OO pada pekerjaan kita, dokumentasi merupakan sesuatu yang mutlak untuk diperhatikan. Untuk programmer java / php, mungkin sudah terbiasa menggunakan source documentation generator seperti JavaDoc atau PhpDoc.

Namun, bagaimana untuk yang menggunakan microsoft .NET? Untuk .NET, ada beberapa software freeware / commercial yang tersedia seperti N-Doc, VSDocMan, dan yang terakhir Sandcastle. Referensi mengenai perbandingan document generator dapat dilihat di wikipedia. Fokus utama yang akan dibahas di dalam artikel ini adalah Sandcastle dengan menggunakan DocProject. Sandcastle adalah software yang dikembangkan oleh microsoft sebagai alat untuk menghasilkan dokumen program dari komentar-komentar yang ada pada sumber program. Sedangkan DocProject merupakan alat bantu untuk sandcastle, karena menggunakan sandcastle secara manual dirasa cukup merepotkan dan membingungkan. Beberapa alasan untuk menggunakan dua software tersebut adalah sbb:

1. Free & Gratis, Sandcastle berlisensi Microsoft Public License, dan DocProject berlisensi GNU/GPL (GPLv2).
2. DocProject lebih mudah digunakan, dan masih didukung oleh komunitas.

Pra-syarat instalasi

1. Download dan Install aplikasi-aplikasi pendukung. (check Prerequisite here)
2. Download Sandcastle (download disini).
3. Download DocProject (download disini).

Langkah-langkah instalasi (How To..)

1. Pastikan syarat-syarat telah terpenuhi.
2. Install Sandcastle.
3. Periksa variable %DXROOT% di System Environment. DXROOT harus menunjuk path dimana sandcastle berada.
4. Install DocProject.
5. Konfigurasi DocProject.

Menggunakan DocProject

DocProject menyertakan project template untuk visual studi 2005 dan 2008 dengan nama DocSite dan DocProject. DocSite untuk sumber program yang berupa website, sedangkan DocProject untuk sumper program yang berupa windows application / class library. Berikut ini adalah best practice yang disimpulkan oleh penulis:

1. Gunakan solution untuk pekerjan anda. Solution berguna untuk melakukan integrasi project-project anda yang mungkin saja terpisah-pisah.
2. Dalam solution yang telah anda buat, klik add -> new project, pilih DocProject (atau DocSite untu website).
3. Konfigurasi wizard yang tampil.
4. Catatan #1: Anda mungkin gagal, apabila membuat DocProject terpisah, dan menambahkan dalam solusi anda, karena salah konfigurasi project.
5. Catatan #2: Pastikan seluruh library yang anda pakai, tersedia dalam versi yang benar. Pastikan tidak ada library yang salah mengacu pada versi .NET yang salah atau tidak ada.  Ini terjadi karena bug dari mrefbuild. Saat proses kompilasi, mrefbuild akan memastikan seluruh referensi tersedia. Sebagai contoh, saya menggunakan ODP.NET Oracle dimana ODP tsb dicompile dengan menggunakan .NET Framework versi 1.0. Maka .NET Framework tersebut harus ada, atau akan terjadi error karena tidak ada reference.
6. Build project DocProject anda.
7. Hasil dokumentasi ada di folder bin.

Semoga membantu.