Her zaman Java API, genelde belgelerine sevdim, ama bazı insanlar onları eksik olarak gördüğünü biliyorum. Ben de merak ettim, sen API belgelerine iyi bir örnek nedir?

Lütfen, bir bağlantı ya da herhangi bir yanıt gerçek bir örnek vardır. Ben (ve diğerleri, tabii ki) kendi belgeleri geliştirmek için kullanabileceğiniz kaynaklar olmasını istiyorum.

İyi bir belgeleme olması GEREKİR:

• veri özellikleri - genellikle gerçek işlevleri daha önemli. Bu yabana.
• gözlük (ortada) işlevi. Bu neden verilen işlev de dahil olmak üzere, belli etmeden ve varsa yanlışlıklar.
• mantıksal bir varlık haline getiren bütün giriş belgesi, niyetlerini açıklayan, gerçek API kodu kapsamı dışında kullanım şekilleri ve fikirleri doğru. Normalde 50 farklı fonksiyonlar verilir ve bilmiyorsungerekirdaha karanlık alternatifler için öngörülmüş özel durumlar dışında kullanılmamalı ve neden o şekilde kullanılmalıdır kullandılar.
• örnekler. Bazen diğerlerinden çok daha önemli

GTK rastgele renk rastgele bir şekil çizmek için nasıl biliyorum . Ben hala çizim renk değişikliği kod çok karanlık, çok sezgisel olmayan çizgiler oldukça uzun üç satır gerektirir neden hiçbir ipucu var. SVGAlib hatırlamak setcolorRGB(r,g,b); draw(x1,y1,x2,y2); gerçekten zor GTK yazarları şeyler çok karmaşık neyin ittiğini anlamak buluyorum. Belki de sadece bunları kullanmak işlevler belgeleyen yerine temel kavramlarını izah ederseniz anlarım...

Başka bir örnek: dün beni SQLite anlamak için izin veren bir cevap aldım. Bir fonksiyonu bir sütun döndürür signed long long veri ayıklanıyor anladım. Tamsayı sütunlar 1,2,4,6 ve 8 bayt uzunluğunda olabilir anladım. Bir sütun tanımlamak ben anladım "İNT8", ya da "". (VARSAYILAN) İMZASIZ olarak Çok şeyi alamadım "yakınlık" ifade etmiştim, ikisi de biliyordu "TAMSAYI" benzeşme. Saat zaman TAMSAYI veya İNT8, ister İNT8 8 haneli veya 8 bayt İŞARETSİZ olup olmadığını ve 6 baytlık int ezoterik adı ne arayan geçirdim?

Ne kaçırdım "İMZASIZ İNT8", "VARSAYILAN" gibi bir cümle şeker eşanlamlıları "İNTEGER" tipi (hep signed long long) ve uzunlukları verilmiştir dahili disk depolama sadece, ayarlanabilir şeffaf ve otomatik olarak uygun herhangi bir değer üzerinde az sayıda bit ve tamamen görünmez ve ulaşılmaz gelen API yan.