appledoc

Tentang appledoc

PEMBERITAHUAN PENTING: dibutuhkan kolaborator

appledoc adalah alat baris perintah yang membantu pengembang Objective-C menghasilkan dokumentasi kode sumber seperti Apple dari komentar kode sumber yang diformat khusus. Ini dirancang untuk mengambil komentar kode sumber yang dapat dibaca untuk masukan dan penggunaan komentar serta kode sumber di sekitarnya untuk menghasilkan dokumentasi yang menarik secara visual dalam bentuk HTML serta kumpulan dokumentasi Xcode yang sepenuhnya diindeks dan dapat dijelajahi. Meskipun ada beberapa alat yang dapat membuat dokumentasi HTML untuk Objective-C, semua alat yang saya ketahui gagal memenuhi tujuan minimum yang dijelaskan di bawah.

Tujuan utama appledoc:

• Komentar kode sumber yang dapat dibaca manusia.
• Referensi silang sederhana ke objek dan anggota.
• Hasilkan dokumentasi HTML kode sumber seperti Apple.
• Hasilkan dan instal kumpulan dokumentasi Xcode yang sepenuhnya diindeks dan dapat dijelajahi.
• Alat tunggal untuk mendorong pembuatan dari penguraian kode sumber hingga instalasi kumpulan dokumentasi.
• Keluaran yang mudah disesuaikan.
• Implementasi Objective-C 100% untuk kemudahan debugging.

Untuk membuat pengalaman Anda dengan appledoc selancar mungkin, kami sangat menyarankan untuk membaca seluruh dokumen ini serta semua dokumentasi online yang disebutkan di bagian "menggunakan appledoc" di bawah!

Penggunaan appledoc diperbolehkan berdasarkan ketentuan yang tercantum di bagian LISENSI di bagian bawah file ini!

Ingin terus mendapat informasi terkini? Ikuti kami di Twitter - @gentlebytes.

Instal cepat

Cara yang disarankan adalah mengkloning proyek GitHub dan mengkompilasi alat dari Xcode. Karena proyek kloning GitHub akan membuat tautan ke repositori utama, hal ini juga sangat menyederhanakan peningkatan di masa mendatang. Untuk menginstal, ketikkan perintah berikut di Terminal:

 git clone git://github.com/tomaz/appledoc.git

Ini menciptakan direktori appledoc. Di dalamnya Anda dapat menemukan ruang kerja appledoc.xcworkspace Xcode; buka dan kompilasi target appledoc - ini akan langsung berfungsi, namun sistem Anda harus memenuhi persyaratan sistem minimum, lihat di bawah. Saya sarankan Anda menyalin hasil appledoc yang dapat dieksekusi dari direktori build ke salah satu direktori di jalur Anda ( echo $PATH ) agar mudah diakses.

Opsional: Appledoc bersifat mandiri dan berisi file templat yang diperlukan. JIKA Anda ingin mengubah default ini dari subdirektori Templat ke salah satu lokasi yang diharapkan:

• ~/Perpustakaan/Dukungan Aplikasi/appledoc
• ~/.appledoc

Anda juga dapat menggunakan skrip install-appledoc.sh untuk melakukan instalasi cepat. Buka Terminal dan beralih ke direktori appledoc. Ketik perintah berikut:

 sudo sh install-appledoc.sh (if you need templates add '-t default')

Ini mengkompilasi appledoc dan menginstal binernya ke /usr/local/bin dan templat (jika diinginkan) ke ~/.appledoc secara default. Anda dapat mengganti direktori ini dengan opsi -b dan -t. Misalnya:

 sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application Support/appledoc

Alternatifnya dengan Homebrew:

 brew install appledoc

Homebrew tidak menginstal template secara default.

Menggunakan appledoc

Gunakan appledoc --help untuk melihat daftar semua saklar baris perintah. Baca lebih lanjut tentang appledoc di situs appledoc. Baca juga halaman wiki untuk beberapa artikel lebih mendalam.

Gunakan grup Google appledoc sebagai forum untuk pertanyaan tentang penggunaan atau pertanyaan umum lainnya.

Gunakan halaman masalah appledoc untuk mengirimkan permintaan bug dan fitur. Sebelum mengirimkan masalah baru, periksa forum untuk melihat apakah pertanyaan Anda terjawab di sana - kecuali Anda dapat mengonfirmasi masalah Anda sebagai permintaan fitur baru atau bug, Anda harus mulai dari forum untuk menjaga masalah GitHub tetap bersih. Baca juga terbitan untuk melihat apakah terbitan tersebut sudah ada dan berikan suara atau tambahkan komentar (jangan lupa tentang terbitan yang sudah ditutup).

Kiat instalasi

Untuk tetap mendapatkan informasi terbaru, cukup buka Terminal dan cd ke direktori appledoc, jalankan git pull dan kompilasi ulang appledoc.xcodeproj. Jangan lupa untuk menimpa appledoc executable yang telah Anda salin ke $PATH :)

Jika Anda juga ingin mengkompilasi dan menjalankan target AppledocTests (pengujian unit), Anda perlu menyalin semua kerangka kerja yang ditunjukkan dalam grup Perpustakaan & Kerangka Kerja ke direktori kerangka kerja bersama sebelum membuat target pengujian unit! Ini tidak diperlukan untuk membuat alat appledoc itu sendiri.

Mengintegrasikan dengan Xcode

Anda dapat mengatur Xcode untuk mengotomatiskan pembuatan dokumen appledoc. Cari tahu cara menggunakan Run Script dan Fase Pembuatan proyek Anda.

Tips penggunaan Docset

Dokumentasi dan dokumen yang telah dibuat sebelumnya untuk sebagian besar kerangka kerja Kakao tersedia di:

• KakaoDoks

Setelah Anda memiliki kumpulan dokumen, Anda mungkin ingin menggunakannya dengan browser dokumentasi:

• kode X
• lari

Pemecahan masalah

Punya masalah? Inilah yang dapat Anda lakukan untuk memecahkan masalah:

1. Pastikan Anda memiliki versi appledoc terbaru. Coba git pull dan jalankan lagi dengan versi terbaru.
2. JIKA Anda telah menginstal file templat, pastikan Anda menggunakan yang terbaru - hapus folder yang telah ditentukan sebelumnya dan minta appledoc menyalin kembali file tersebut dari arsip yang tertanam (lihat bagian Instalasi Cepat di atas).
3. Tingkatkan tingkat verbositas dengan saklar baris perintah --verbose . Level defaultnya adalah 2, namun Anda dapat meningkatkan verbositas secara bertahap hingga 6 dengan setiap level memberi Anda informasi yang lebih detail. Karena ini akan memberi Anda lebih banyak informasi, Anda mungkin ingin berkonsentrasi hanya pada kumpulan file sumber tertentu yang bermasalah. Perhatikan bahwa peningkatan verbositas akan mengakibatkan kinerja lebih lambat sehingga tidak disarankan menggunakan level di atas 4 untuk penggunaan sehari-hari.
4. Appledoc adalah proyek sumber terbuka! Anda memiliki semua kode sumber yang tersedia, jadi jalankan dari Xcode. Anda dapat mengatur Xcode untuk meneruskan argumen baris perintah yang diinginkan dan menambahkan breakpoint untuk membantu Anda mengisolasi masalah Anda. Jika Anda merasa ingin berkontribusi lebih banyak kepada komunitas, Anda dipersilakan untuk membuat proyek di GitHub dan menambahkan fitur ke dalamnya. Terus kabari kami agar kami juga dapat menambahkan fitur-fitur ini ke repositori utama - sertakan pengujian unit jika memungkinkan.
5. Jika Anda merasa menemukan bug atau ingin meminta fitur baru, buka halaman masalah appledoc. Pertama-tama baca masalah yang ada untuk melihat apakah sudah ada permintaan di sana (jika Anda menggunakan cabang master, baca juga masalah yang ditutup karena permintaan Anda mungkin sudah tercakup tetapi belum digabungkan di cabang master). Anda dapat memilih permintaan yang ada untuk membantu kami memutuskan fitur mana yang menjadi fokus atau Anda dapat menambahkan komentar untuk membantu menyelesaikannya. Jika Anda tidak menemukan permintaan tersebut di sana, buatlah terbitan baru; sertakan bagian dari file sumber yang memberi Anda masalah jika memungkinkan dan/atau deskripsi atau langkah-langkah yang mengarah ke masalah tersebut.
6. Jika Anda mengalami masalah dengan beberapa file sumber dan tidak ingin mempublikasikannya secara online, Anda dapat menghubungi kami melalui email di bawah. Kami akan melakukan yang terbaik untuk membantu Anda, namun ingatlah bahwa appledoc bukanlah produk komersial; itu dibuat dan dipelihara di waktu luang kita, jadi sumber dayanya terbatas.

Catatan pengembang

Jika Anda ingin berkontribusi, lihat file Catatan Pengembang untuk gambaran singkat tentang cara kerja appledoc secara internal.

Persyaratan sistem minimum

• Xcode 4.5 atau lebih tinggi untuk kompilasi
• OS X 10.7 untuk kompilasi dan pengoperasian

Lisensi

appledoc dilisensikan dengan lisensi BSD yang dimodifikasi. Dalam bahasa yang sederhana: Anda diperbolehkan melakukan apa pun yang Anda inginkan dengan kode, memodifikasi, mendistribusikan ulang, menyematkan produk Anda (gratis atau komersial), tetapi Anda harus menyertakan hak cipta, syarat penggunaan, dan penafian sebagaimana tercantum dalam lisensi, sama saja sama seperti kode berlisensi BSD lainnya. Tentu saja Anda dapat menggunakan dokumentasi yang dihasilkan oleh appledoc untuk produk Anda (gratis atau komersial), namun Anda harus mengaitkan appledoc baik dalam dokumentasi itu sendiri atau di tempat lain yang sesuai seperti situs web Anda.

Jika karena alasan apa pun Anda tidak dapat menyetujui persyaratan ini, hubungi kami melalui formulir kontak di halaman tentang kami, kami akan melakukan yang terbaik untuk membantu Anda dan menemukan solusi yang bisa diterapkan!

Hak Cipta (c) 2009-2011, Gentle Bytes Semua hak dilindungi undang-undang.

Pendistribusian ulang dan penggunaan dalam bentuk sumber, biner, dan dokumentasi yang dihasilkan, dengan atau tanpa modifikasi, diperbolehkan asalkan kondisi berikut terpenuhi:

• Pendistribusian ulang kode sumber harus tetap memperhatikan pemberitahuan hak cipta di atas, daftar ketentuan ini, dan penafian berikut.

• Redistribusi dalam bentuk biner harus mereproduksi pemberitahuan hak cipta di atas, daftar ketentuan ini dan penafian berikut dalam dokumentasi dan/atau materi lain yang disediakan bersama distribusi.

• Redistribusi dokumentasi yang dihasilkan oleh appledoc harus menyertakan atribusi ke appledoc, baik dalam dokumentasi itu sendiri atau media lain yang sesuai.

• Baik nama appledoc, Gentle Bytes maupun nama kontributornya tidak boleh digunakan untuk mendukung atau mempromosikan produk turunan dari perangkat lunak ini tanpa izin tertulis khusus sebelumnya.

PERANGKAT LUNAK INI DISEDIAKAN OLEH PEMEGANG HAK CIPTA DAN KONTRIBUTOR "APA ADANYA" DAN JAMINAN TERSURAT MAUPUN TERSIRAT, TERMASUK, NAMUN TIDAK TERBATAS PADA, JAMINAN TERSIRAT ATAS KELAYAKAN UNTUK DIPERDAGANGKAN DAN KESESUAIAN UNTUK TUJUAN TERTENTU DITOLAK. DALAM KEADAAN APA PUN PEMEGANG HAK CIPTA ATAU KONTRIBUTOR TIDAK BERTANGGUNG JAWAB ATAS KERUSAKAN LANGSUNG, TIDAK LANGSUNG, INSIDENTAL, KHUSUS, CONTOH, ATAU KONSEKUENSIAL (TERMASUK, NAMUN TIDAK TERBATAS PADA, PENGADAAN BARANG ATAU JASA PENGGANTI; KEHILANGAN PENGGUNAAN, DATA, ATAU KEUNTUNGAN; ATAU BISNIS GANGGUAN) APAPUN PENYEBABNYA DAN PADA TEORI TANGGUNG JAWAB APA PUN, BAIK DALAM KONTRAK, TANGGUNG JAWAB KETAT, ATAU HUKUM (TERMASUK KELALAIAN ATAU LAINNYA) YANG TIMBUL DALAM PENGGUNAAN PERANGKAT LUNAK INI, MESKIPUN DIBERITAHU TENTANG KEMUNGKINAN KERUSAKAN TERSEBUT.

Byte Lembut [email protected]