autogsdoc - Pembuat dokumentasi API GNUstep dan konverter XML->HTML
autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO] [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-DocumentationDirectory path] [-Declared location] [-Project title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate filename] [-VariablesTemplate filename] [-SystemProjects string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
Alat autogsdoc adalah utilitas baris perintah yang membantu pengembang membuat dokumentasi referensi untuk API GNUstep. Itu juga memungkinkan pengembang untuk menulis dan memelihara dokumentasi lain dalam XML dan mengubahnya menjadi HTML. Secara detail, autogsdoc akan:
Ekstrak komentar khusus yang menjelaskan antarmuka publik kelas, kategori, protokol, fungsi, dan makro dari kode sumber Objective C (file header dan file sumber opsional) ke dalam file XML GSDoc.
Mengonversi file XML GSDoc, baik yang dihasilkan dari kode sumber atau ditulis secara manual oleh pengembang, menjadi HTML.
Buat indeks berdasarkan kumpulan file XML GSDoc, dan konversikan juga ke HTML.
Penggunaan yang paling umum adalah menjalankan perintah dengan satu atau lebih nama file header sebagai argumen ... alat ini akan secara otomatis mengurai file sumber yang sesuai di direktori yang sama dengan header (atau direktori saat ini, atau direktori yang ditentukan menggunakan DocumentationDirectory default), dan menghasilkan file GSDoc dan HTML sebagai output. Untuk hasil terbaik, mode ini harus dijalankan dari direktori yang berisi file sumber. (Perhatikan bahwa karena C adalah subset dari Objective C, alat ini dapat beroperasi untuk mendokumentasikan fungsi dan struktur C lainnya dalam sumber C biasa.)
File GSDoc juga dapat diberikan secara langsung sebagai tambahan atau sendiri, dan akan dikonversi ke HTML. Lihat dokumentasi HTML GSDoc atau halaman manual gsdoc(7) untuk informasi tentang format GSDoc.
Akhirnya, file HTML dapat diberikan pada baris perintah. Referensi silang ke bagian lain dari dokumentasi kode yang ditemukan di dalamnya akan ditulis ulang berdasarkan apa yang ditemukan dalam proyek saat ini.
Pengurai kode sumber akan secara otomatis menghasilkan dokumen GSDoc yang mencantumkan metode dalam kelas yang ditemukan di file sumber, dan akan menyertakan teks dari komentar yang diformat khusus dari file sumber.
Setiap komentar yang dimulai dengan garis miring dan dua tanda bintang, bukan garis miring biasa dan tanda bintang tunggal, dianggap sebagai markup GSDoc, untuk digunakan sebagai deskripsi kelas atau metode yang mengikutinya. Teks komentar ini diformat ulang dan kemudian dimasukkan ke dalam output.
Jika beberapa komentar diasosiasikan dengan item yang sama, komentar tersebut digabungkan dengan jeda baris (
) di antara masing-masing jika perlu.Alat ini dapat dengan mudah digunakan untuk mendokumentasikan program dan juga pustaka, cukup dengan memberinya nama file sumber yang berisi fungsi main() dari program - diperlukan komentar khusus dari fungsi tersebut dan menanganinya secara khusus, menyisipkannya sebagai bagian di akhir bab pertama dokumen (ini membuat bab pertama jika perlu).
Opsi dijelaskan di bagian Argumen dan Default di bawah.
Ada beberapa kasus di mana pemrosesan ekstra khusus dilakukan, terutama di komentar pertama yang ditemukan di file sumber, yang darinya berbagai potongan markup GSDoc dapat diekstraksi dan ditempatkan di lokasi yang sesuai di dokumen keluaran -
Di baris mana pun AutogsdocSource: ditemukan, sisa baris diambil sebagai nama file sumber yang akan digunakan alih-alih membuat asumsi bahwa setiap file .h yang diproses menggunakan file .m yang sama nama. Anda dapat menyediakan beberapa baris AutogsdocSource: tempat file header mendeklarasikan item yang ditentukan dalam beberapa file sumber. Jika nama file mutlak, digunakan seperti yang disediakan. Sebaliknya, jika itu adalah jalur relatif, perangkat lunak mencari file sumber terlebih dahulu relatif terhadap lokasi file header, dan jika tidak ditemukan di sana, relatif terhadap direktori saat ini di mana autogsdoc berjalan, dan akhirnya relatif terhadap direktori yang ditentukan oleh default DocumentationDirectory.
Abstrak konten dokumen ... ditempatkan di kepala keluaran GSDoc.
Deskripsi pembuat kode - dapat diulang untuk menangani kasus di mana dokumen memiliki banyak penulis. Ditempatkan di kepala keluaran GSDoc. Sebagai bantuan untuk keterbacaan sumber, beberapa pemrosesan tambahan khusus dilakukan terkait dengan penulis dokumen - Setiap baris formulir
nama
nama
nama' atau
name' akan dikenali dan dikonversi menjadi elemen penulis, mungkin berisi elemen email.
Ditempatkan di keluaran GSDoc tepat sebelum bagian akhir badan dokumen - dimaksudkan untuk digunakan untuk lampiran, indeks, dll..
Ditempatkan tepat sebelum dokumentasi kelas apa pun yang dibuat ... dimaksudkan untuk digunakan untuk memberikan deskripsi keseluruhan tentang cara kerja kode yang didokumentasikan. Setiap dokumentasi untuk fungsi main() dari sebuah program dimasukkan sebagai bagian di akhir bab ini.
Hak cipta konten dokumen ... ditempatkan di kepala keluaran GSDoc. Sebagai bantuan untuk keterbacaan sumber, beberapa pemrosesan tambahan khusus dilakukan - Setiap baris dalam bentuk 'Teks Hak Cipta (C)' akan dikenali dan diubah menjadi elemen salinan.
Tanggal revisi dokumen ... ditempatkan di kepala keluaran GSDoc. Jika ini dihilangkan, alat akan mencoba membuat nilai dari tag Tanggal RCS (jika tersedia).
Dimasukkan ke dalam dokumen di awal badan ... dimaksudkan untuk menyediakan halaman pengantar atau konten dll.
Judul dokumen ... ditempatkan di kepala keluaran GSDoc. Jika ini dihilangkan, alat akan menghasilkan judulnya sendiri (mungkin buruk) - jadi Anda harus menyertakan markup ini secara manual.
Pengidentifikasi versi dokumen ... ditempatkan di kepala keluaran GSDoc. Jika ini dihilangkan, alat akan mencoba membuat nilai dari tag Revisi RCS (jika tersedia).
NB Markup yang baru saja dijelaskan dapat digunakan dalam dokumentasi kelas, kategori, atau protokol ... jika demikian, markup tersebut diekstrak dan dibungkus dengan dokumentasi lainnya untuk kelas sebagai bab kelas. Dokumentasi kelas lainnya biasanya disisipkan di akhir bab, tetapi dapat diganti sebagai pengganti elemen semu
Dalam komentar yang digunakan untuk menyediakan teks untuk deskripsi metode, markup berikut dihapus dari teks dan ditangani secara khusus -
Metode ditandai sebagai penginisialisasi yang ditunjuk untuk kelas.
Metode ini ditandai sebagai salah satu yang harus ditimpa oleh subkelas (misalnya metode abstrak).
Metode ini ditandai sebagai metode yang TIDAK harus ditimpa oleh subkelas.
Markup dihapus dari deskripsi dan ditempatkan setelah di keluaran GSDoc - sehingga metode tersebut dijelaskan sesuai (atau tidak sesuai) dengan standar yang ditentukan.
Umumnya, teks dalam komentar diformat ulang untuk dibakukan dan diindentasi dengan baik ... pemformatan ulang tidak dilakukan pada teks mana pun di dalam elemen
Konstanta terkenal tertentu seperti YES, NO, dan nil dilampirkan dalam markup ... .
Nama argumen metode dalam deskripsi metode dilampirkan dalam markup ... .
Nama metode (dimulai dengan plus atau minus) dilampirkan dalam markup
Penentu metode termasuk nama kelas (dimulai dan diakhiri dengan tanda kurung siku) diapit oleh markup
Nama fungsi (diakhiri dengan '()') selain 'main()' diapit oleh markup
Alat ini menerima default pengguna tertentu (yang tentu saja dapat diberikan sebagai argumen baris perintah dengan menambahkan '-' sebelum nama default dan memberikan nilai setelahnya, seperti pada -Bersihkan YA):
Jika nilai boolean ini disetel ke YA, alih-alih menghasilkan dokumentasi, alat ini akan menghapus semua file GSDoc yang dihasilkan dalam proyek, dan semua file html yang dihasilkan darinya (serta file yang akan dihasilkan dari file GSDoc yang dicantumkan secara eksplisit), dan akhirnya menghapus file indeks proyek. Satu-satunya pengecualian untuk hal ini adalah file template GSDoc (yaitu yang ditentukan menggunakan argumen "-ConstantsTemplate ...", "-FunctionsTemplate ...", dll.) tidak akan dihapus kecuali flag CleanTemplates disetel.
Bendera ini menentukan apakah file template GSDoc akan dihapus bersama dengan file lain saat opsi Bersihkan ditentukan. Standarnya adalah agar mereka tidak dihapus ... karena templat ini mungkin dibuat secara manual dan baru saja memasukkan data ke dalamnya.
Tentukan nama dokumen template tempat dokumentasi tentang konstanta harus dimasukkan dari semua file dalam proyek. Ini berguna jika konstanta dalam kode sumber tersebar di banyak file, dan Anda perlu mengelompokkannya ke dalam satu tempat. Anda bertanggung jawab untuk memastikan bahwa dokumen templat dasar (di mana dokumentasi konstan individu dimasukkan) berisi semua informasi lain yang Anda inginkan, tetapi sebagai kemudahan autogsdoc akan menghasilkan templat sederhana (yang kemudian dapat Anda edit) untuk Anda jika file tersebut tidak. tidak ada. Penyisipan dilakukan tepat sebelum elemen back (atau jika tidak ada, segera sebelum akhir elemen body) di template.
Tentukan di mana tajuk harus didokumentasikan saat ditemukan. Nama aktual yang dihasilkan dalam dokumentasi dibentuk dengan menambahkan komponen terakhir dari nama file header ke nilai default ini. Jika standar ini tidak ditentukan, nama lengkap file header (seperti yang disediakan pada baris perintah), dengan awalan HeaderDirectory, akan digunakan. Penggunaan tipikal ini mungkin adalah '"-Declared Foundation"' saat membuat dokumentasi untuk pustaka dasar GNUstep. Ini akan menghasilkan dokumentasi yang mengatakan bahwa NSString dideklarasikan di 'Foundation/NSString.h'
Bendera ini memungkinkan Anda membuat dokumentasi untuk semua variabel instan. Biasanya, hanya yang secara eksplisit dinyatakan 'publik' atau 'dilindungi' yang akan didokumentasikan.
Bendera ini mengizinkan Anda untuk mematikan dokumentasi untuk variabel instan sepenuhnya. Biasanya, variabel instan 'publik' atau 'dilindungi' yang dinyatakan secara eksplisit akan didokumentasikan.
Bendera ini, jika disetel, mengarahkan generator HTML untuk menempatkan dokumentasi variabel instan di akhir kelas, bukan di awal. Ini berguna jika Anda menggunakan banyak variabel instance yang dilindungi yang hanya akan menjadi kepentingan sekunder bagi pengguna umum kelas tersebut.
Dapat digunakan untuk menentukan direktori di mana dokumentasi yang dihasilkan akan ditempatkan. Jika ini tidak disetel, keluaran ditempatkan di direktori saat ini. Direktori ini juga digunakan sebagai pilihan terakhir untuk mencari file sumber (bukan header), dan yang lebih penting, ini digunakan sebagai pilihan pertama dan satu-satunya untuk mencari file .gsdoc yang diteruskan ke garis komando. Setiap informasi jalur yang diberikan untuk file ini dihapus dan dicari di 'DocumentationDirectory' (meskipun mungkin belum dibuat secara otomatis).
Menentukan nama file yang berisi daftar nama file sebagai array daftar properti format (name1,name2,...). Jika ini ada, nama file dalam daftar argumen program diabaikan dan nama dalam file ini digunakan sebagai daftar nama untuk diproses.
Tentukan nama dokumen template tempat dokumentasi tentang fungsi harus disisipkan dari semua file dalam proyek. Ini berguna jika kode sumber fungsi tersebar di banyak file, dan Anda perlu mengelompokkannya ke dalam satu tempat. Anda bertanggung jawab untuk memastikan bahwa dokumen templat dasar (di mana dokumentasi fungsi individu dimasukkan) berisi semua informasi lain yang Anda inginkan, tetapi sebagai kemudahan, autogsdoc akan menghasilkan templat sederhana (yang kemudian dapat Anda edit) untuk Anda jika file tersebut tidak. tidak ada. Penyisipan dilakukan tepat sebelum elemen back (atau jika tidak ada, segera sebelum akhir elemen body) di template.
Dapat digunakan untuk menentukan apakah keluaran HTML akan dihasilkan. Default ke YA.
Dapat digunakan untuk menentukan direktori yang akan dicari file header. Saat diberikan, nilai ini ditambahkan ke nama header relatif, jika tidak, nama header relatif ditafsirkan relatif terhadap direktori saat ini. File header yang ditentukan sebagai jalur absolut tidak dipengaruhi oleh default ini.
Nilai boolean yang dapat digunakan untuk menentukan bahwa program harus mengabaikan waktu modifikasi file dan tetap membuat ulang file. Disediakan untuk digunakan bersama dengan sistem 'make', yang diharapkan dapat mengelola pemeriksaan ketergantungan itu sendiri.
Nilai ini digunakan untuk mengontrol penyertaan otomatis proyek eksternal lokal ke dalam sistem pengindeksan untuk pembuatan referensi silang dalam keluaran dokumen akhir. Jika disetel ke 'None', maka tidak ada referensi proyek lokal yang dikerjakan, jika tidak, direktori dokumentasi GNUstep 'Lokal' secara rekursif mencari file dengan ekstensi '.igsdoc', dan informasi pengindeksan dari file tersebut digunakan. Nilai string ini juga digunakan untuk menghasilkan nama file dalam referensi silang ... jika ini adalah string kosong, jalur yang digunakan diasumsikan sebagai file di direktori yang sama tempat file igsdoc ditemukan, jika tidak maka digunakan sebagai awalan nama dalam indeks. NB. Proyek lokal dengan nama yang sama dengan proyek yang saat ini sedang didokumentasikan tidak akan disertakan oleh mekanisme ini. Jika Anda ingin menyertakan proyek semacam itu, Anda harus melakukannya secara eksplisit menggunakan -Projects ...
Tentukan nama dokumen template tempat dokumentasi tentang makro harus disisipkan dari semua file dalam proyek. Ini berguna jika kode makro tersebar di banyak file, dan Anda perlu mengelompokkannya ke dalam satu tempat. Anda bertanggung jawab untuk memastikan bahwa dokumen templat dasar (di mana dokumentasi makro individu dimasukkan) berisi semua informasi lain yang Anda inginkan, tetapi sebagai kemudahan autogsdoc akan menghasilkan templat sederhana (yang kemudian dapat Anda edit) untuk Anda jika file tersebut tidak tidak ada. Penyisipan dilakukan tepat sebelum elemen back (atau jika tidak ada, segera sebelum akhir elemen body) di template.
Nama file yang akan digunakan untuk menampilkan informasi dependensi untuk make. Ini akan berupa daftar semua file header dan sumber yang dikenal untuk proyek sebagai dependensi dari nama proyek (lihat 'Proyek').
Dapat digunakan untuk menentukan nama proyek ini ... menentukan nama file referensi indeks yang dihasilkan sebagai bagian dari dokumentasi untuk memberikan informasi yang memungkinkan proyek lain untuk referensi silang ke item dalam proyek ini.
Nilai ini dapat diberikan sebagai kamus yang berisi jalur ke file indeks/referensi igsdoc yang digunakan oleh proyek eksternal, bersama dengan nilai yang akan digunakan untuk memetakan nama file yang ditemukan di indeks. Misalnya, jika file indeks proyek (igsdoc) mengatakan bahwa kelas 'Foo' ditemukan di file 'Foo', dan jalur yang terkait dengan indeks proyek tersebut adalah '/usr/share/doc/proj', maka dihasilkan html output dapat merujuk kelas sebagai di '/usr/share/doc/prj/Foo.html' . Perhatikan bahwa kamus dapat diberikan pada baris perintah dengan menggunakan format PropertyList standar (bukan format XML OS X), menggunakan titik koma sebagai pemisah baris, dan melampirkannya dalam tanda kutip tunggal.
Nilai boolean yang dapat digunakan untuk menentukan bahwa program harus mencatat file mana yang dibuat ulang karena ketergantungannya pada file lain.
Nilai boolean yang digunakan untuk menentukan apakah program harus memasukkan informasi tentang kepatuhan standar ke dalam dokumentasi. Ini hanya boleh digunakan saat mendokumentasikan pustaka dan alat GNUstep itu sendiri karena mengasumsikan bahwa kode yang didokumentasikan adalah bagian dari GNUstep dan mungkin sesuai dengan standar OpenStep atau mengimplementasikan metode yang kompatibel dengan MacOS-X.
Nilai ini digunakan untuk mengontrol penyertaan otomatis proyek eksternal sistem ke dalam sistem pengindeksan untuk pembuatan referensi silang dalam keluaran dokumen akhir. Jika diatur ke 'None', maka tidak ada referensi proyek sistem yang dilakukan, jika tidak, direktori dokumentasi GNUstep 'Sistem' secara rekursif mencari file dengan ekstensi '.igsdoc', dan informasi pengindeksan dari file tersebut digunakan. Nilai string ini juga digunakan untuk menghasilkan nama file dalam referensi silang ... jika ini adalah string kosong, jalur yang digunakan diasumsikan sebagai file di direktori yang sama tempat file igsdoc ditemukan, jika tidak maka digunakan sebagai awalan nama dalam indeks. NB. Proyek sistem dengan nama yang sama dengan proyek yang saat ini sedang didokumentasikan tidak akan disertakan oleh mekanisme ini. Jika Anda ingin menyertakan proyek semacam itu, Anda harus melakukannya secara eksplisit menggunakan -Projects ...
Tentukan nama dokumen template tempat dokumentasi tentang typedefs harus dimasukkan dari semua file dalam proyek. Ini berguna jika kode sumber typedef tersebar di banyak file, dan Anda perlu mengelompokkannya ke dalam satu tempat. Anda bertanggung jawab untuk memastikan bahwa dokumen templat dasar (di mana dokumentasi typedef individual dimasukkan) berisi semua informasi lain yang Anda inginkan, tetapi sebagai kenyamanan autogsdoc akan menghasilkan templat sederhana (yang kemudian dapat Anda edit) untuk Anda jika file tersebut tidak. tidak ada. Penyisipan dilakukan tepat sebelum elemen back (atau jika tidak ada, segera sebelum akhir elemen body) di template.
Sebuah string yang digunakan untuk menyediakan nama yang akan digunakan dalam tautan 'naik' dari dokumen GSDoc yang dihasilkan. Ini biasanya harus menjadi nama file yang berisi indeks konten proyek. Jika ini hilang atau disetel ke string kosong, maka tidak ada tautan 'naik' yang akan diberikan dalam dokumen.
Tentukan nama dokumen template tempat dokumentasi tentang variabel harus dimasukkan dari semua file dalam proyek. Ini berguna jika kode sumber variabel tersebar di banyak file, dan Anda perlu mengelompokkannya ke dalam satu tempat. Anda bertanggung jawab untuk memastikan bahwa dokumen templat dasar (di mana dokumentasi variabel individu dimasukkan) berisi semua informasi lain yang Anda inginkan, tetapi sebagai kemudahan autogsdoc akan menghasilkan templat sederhana (yang kemudian dapat Anda edit) untuk Anda jika file tersebut tidak. tidak ada. Penyisipan dilakukan tepat sebelum elemen back (atau jika tidak ada, segera sebelum akhir elemen body) di template.
Sebuah boolean digunakan untuk menentukan apakah Anda ingin output debug/peringatan verbose diproduksi.
Boolean yang digunakan untuk menentukan apakah Anda ingin keluaran peringatan standar (misalnya laporan metode tidak berdokumen) dihasilkan.
Nilai ini adalah kamus yang digunakan untuk memetakan pengidentifikasi/kata kunci yang ditemukan di file sumber ke kata lain. Umumnya Anda tidak perlu menggunakan ini, tetapi kadang-kadang berguna untuk menghindari parser menjadi bingung dengan penggunaan makro preprosesor C. Anda dapat secara efektif mendefinisikan ulang makro menjadi sesuatu yang tidak terlalu membingungkan. Nilai yang Anda petakan untuk pengidentifikasi harus salah satu dari - Pengidentifikasi lain, String kosong - nilai diabaikan, Dua garis miring ('//') - baris lainnya diabaikan. Perhatikan bahwa kamus dapat diberikan pada baris perintah dengan menggunakan format PropertyList standar (bukan format XML OS X), menggunakan titik koma sebagai pemisah baris, dan melampirkannya dalam tanda kutip tunggal.
Standar 'Naik' digunakan untuk menentukan nama dokumen yang harus digunakan sebagai tautan 'naik' untuk dokumen lain yang digunakan. Nama ini tidak boleh menyertakan jalur atau ekstensi. Umumnya, dokumen yang dirujuk secara default ini harus berupa dokumen GSDoc yang diedit dengan tangan yang harus memiliki bagian kembali yang berisi indeks proyek. misalnya
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">
<head>
<title>My project reference</title>
<author name="my name"></author>
</head>
<body>
<chapter>
<heading>My project reference</heading>
</chapter>
<back>
<index scope="project" type="title" />
</back>
</body>
</gsdoc> Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .htmlBeberapa elemen GSDoc belum dirender dengan benar ke dalam HTML. Ini adalah:
Pesan kesalahan dan peringatan dapat berasal dari setiap tahapan alur: kontrol tingkat atas, penguraian sumber, penguraian GSDoc, dan pengindeksan.
gsdoc(7), GNUstep(7)
Autogsdoc menggabungkan kemampuan dari dua alat sebelumnya, 'autodoc' dan 'gsdoc', yang masing-masing melakukan terjemahan sumber->GSDoc dan GSDoc->HTML. Alat dan format GSDoc sebelumnya ini dikembangkan untuk GNUstep berdasarkan bahasa SGML GDML sebelumnya.
Halaman manual ini pertama kali muncul di gnustep-base 1.9.2 (Maret 2004).
autogsdoc ditulis oleh Richard Frith-Macdonald
Halaman manual ini ditambahkan oleh Adrian Robert