Milyen egy jó SDK doksi?

Fejlesztés

Hi!

Szerintetek milyen egy jó SDK dokumentációs oldal? Mi kell rá, mi nem? Mitől zárjátok be azonnal és kerestek másik SDK-t?

Szerintem az MSDN és a http://dev.mysql.com/doc/ felépítése mérvadó, de mondták már nekem, hogy az msdn átláthatatlan...

Véleményetek? Osszátok az észtet, legfeljebb megy flame-be.
Vizuális fikázások is jöhetnek.

  • 10652 megtekintés

( Jason v | 2012. 02. 08., sze – 10:48 )

Én speciel Sandcastle-lel generálok apidocot, ha visual studio-s a projekt. Vagy phpdocu, ha $1.

( Jason v | 2012. 02. 08., sze – 12:52 )

Na, senki sem olvas doksikat? Úgy születtetek, hogy mindent tudtok?

( legradi v | 2012. 02. 08., sze – 13:36 )

Hahó!

Nem csak SDK-ról, de pl. az API-ról (pontosabban a Java API-ról) szóló doksi (itt) felépítése számomra mérvadó (korábban SUN, most Oracle kezelésben), magam is az MSDN-t kissé átláthatatlannak, és hiányosnak érzem, pl. C# esetében.

+ Ilyen típusú doksit -- mint amilyen az API leírás -- a Java programokhoz generáltatni lehet a javadoc programmal.

>> Mi kell rá, mi nem?

Minden ami a megtanulásához (pl. működő és érthető példakódok) és a napi használatához kellhet (nyelvi és programkönyvtári referencia kézikönyv).

G.
P.S.
>> Na, senki sem olvas doksikat? Úgy születtetek, hogy mindent tudtok?
Nem feltétlenül a mindentudás birtoklása az ok, talán csak aki most dolgozik (fejleszt), az nem biztos, hogy épp most a HUP-ot is olvassa fejlesztés közben...
============================================
"Share what you know. Learn what you don't."

( wachag | 2012. 02. 08., sze – 14:37 )

Tartalmaz működő példákat. Leírja, melyik paraméter mit csinál (esetleg azt is, hogy hogyan kell létrehozni, ha esetleg valami context). Leírja, hogy ki vagy bemenő paraméter. Hogy lehet-e NULL/mi lehet default érték. Esetleg leírja az algoritmust is. Nem Doxygen-nel készült. :-)

+1
a legtobb fejleszto a peldakbol latja at leginkabb a mukodest.
legyen teljes api dokumentacio, de amint mar tobben is irjak, az onmagaban keves.
legyen egy high level attekintes a rendszerrol, majd csoportokra bontva az egyes API reszek bemutatasa, szinten szovegesen hogy mi mire jo, milyen fogalmak alatt mit kell erteni (pl. egy vasarlasi/fizetesi rendszernel legyen definialva, hogy mit ertunk vasarlo, termek, kosar, tranzakcio alatt, etc.) majd az egyes muveleteket mutassa be 1-1 rovid peldaval is.
amit meg sok helyrol hianyolok, az annak a bemutatasa, hogy hogyan kell a kulonbozo api hivasokat egyutt hasznalni.
tehat pl. api doksibol kiderul, hogy a rendelesfeladas var egy customer meg egy kosar parametert, de ott nem mutatja be, hogy ezeket hogy kellett letrehozni, inicializalni ahhoz, hogy itt ne kapjunk titokzatos hibauzeneteket.
apropo, hibauzenetek, az API hivasoknal visszaadott hibauzenetek utaljanak a tenyleges problemara, lehetoleg minnel pontosabban behatarolhatoan, a dokumentacio szintugy tartalmazza, a lehetseges hibakodok listaja magyarazattal.
es ha az API tervezes fazisaban vagyunk, akkor erdemes a "principle of least astonishment"-et betartani, ha valami felreertheto/ketertelmu, akkor javitsuk ki, vagy ha nem lehet, akkor legalabb hivjuk fel ra a figyelmet a dokumentacioban, meg esetleg a hibauzenetben is.

es amit meg szeretek, ha van kesz pelda integracio tobb nyelven (de legalabb javaban).

ps: kicsit mar a 3rd party/web service jellegu APIkat is szem elott tartottam a comment irasakor, bar most utolag atfutva talan nincs semmi olyan a hozzaszolasomban, ami egy offline library sdk-ban ertelmetlen lenni.

Tyrael

Apropó, API tervezés: aki ilyenben gondolkodik, annak tudom ajánlani a következő könyvet, mert sok dolgot leír azzal kapcsolatban, mert nem csak magáról a .NET-ről magyaráz, hanem, hogy hogyan érdemes egy API-t, libet tervezni, miket tapasztaltak a .NET tervezése közben, stb.:

http://www.amazon.com/Framework-Design-Guidelines-Conventions-Libraries… (Mondjuk hozzáteszem, 1-2 dologgal azért vannak fenntartásaim, pl. amit a hungarian notationról írt benne a szerző, az nettó fasság.)

Csak egy példa: pl. bemutatja, hogy hogyan alakult ki a nevezéktana a .NET-nek, vagy hogy miért célszerű API tervezéskor először interface-kban gondolkodni és utána a mögöttes implementáláson. (Tehát, hogy először azt írjuk le magunknak, hogy mi az a kód, amit szeretnénk leírni, amikor _használjuk_ az API-t és csak utána foglalkozzunk az implementálással.)

----------------
Lvl86 Troll

( kmARC v | 2012. 02. 09., cs – 09:48 )

Qt dokumentáció is elég összeszedett. A start page kicsit hosszú, de cserébe bármilyen szintű tudással rendelkező neki tud állni (Tutorial kezdőknek, vagy teles API referencia)

Számomra a Modulokat összefoglaló kezdőpont az ideális. Egy osztály leírásának pedig minimum ilyen minőségűnek kell lennie: QIcon. Ez tartalmaz teljes API leírást, tanácsokat a használatra, best practice-eket, kicsit a mélyére is áshatsz a dolognak, és a sok linknek köszönhetően elnavigálhatsz egész más komponesekig, és felmérheted, hogy azokkal hogyan tud az adott egység együttműködni. Néha komolyan, bele is feledkezem a Qt-doc böngészésbe; annyira olvasmányos :)

( Nyosigomboc v | 2012. 02. 09., cs – 09:48 )

-legyen az elejen valami attekintes, ne a kis darabokbol kelljen osszerakni a teljes kepet.. pl. ami az Androidnal az Application Fundamentals
-legyen referencia (szoval irja le az adott topicrol (fuggveny/class/metodus/stb.), hogy hogy mukodik, mit csinal, mik a parameterei)
-legyen mindenkeppen legalabb egy egyszeru lecsupaszitott peldakod, ami lehetoleg onmagaban mukodik (ebbol a Turbo Pascal helpje volt nagyon jo).. lehet olyan is, hogy egy kod tobb fuggvenyhez is be van linkelve
-plusz, de mindenkepp elony, ha van egy olyan pelda is, ami a "best practice" (tipikus hibak lekezelesevel egyutt)
-ha van lehetoseg valami community-s kiegeszitesre - akar tipikus hiba, akar peldakod, akar egyeb hozzafuznivalo, ami esetleg kesobb a hivatalosba is bekerulhet - az mindenkeppen elony (persze ha van mogotte par ember).. tipikusan a Postgres doksija ilyen (es meg a php.net is hasonlo)

--
In 2000 years time, historians studying the national census will think we murdered all the Jedi.

Gondolom ismered a regularis kifejezeseket. En is ismerem jopar eve. Ha megnezed mondjuk a http://hu.php.net/manual/en/function.preg-match.php oldalt, az elejen leirjak, hogy PHP-ban hogy kell hasznalni a PCRE libraryt, par peldaval. Ez hasznos azoknak, akik nem tudjak. Utana jon egy csomo copy-paste-friendly kodreszlet, ami bizonyos esetekben jol johet, es amit csak rengeteg doksiolvasas aran tudnal csak magadtol eloallitani (pl. hogy kell bekapcsolni az UTF8 tamogatast, ha alapbol anelkul fordult).
Nem forum, mert nem problemakat oldanak meg (jo, persze olyan is elofordul), hanem foleg hasznos kodreszleteket/figyelmezteteseket osztanak meg egymassal.
Persze a PHP-re jellemzo, hogy khm.. eleg sok kezdo muveli, szoval nem feltetlenul kell keszpenznek venni minden hulyeseget, amit leirnak. De neha jol tud jonni az effele. Par nap/het szivast osszessegeben siman meg tud sporolni (nem konkretan a regexpnel, hanem ugy altalanossagban).

Ha az SDK-t te fejleszted, neked teljesen trivialis lehet valami, ami egy felhasznalonak nem az. Ennel kozvetlenebb visszajelzes nem nagyon van.

--
In 2000 years time, historians studying the national census will think we murdered all the Jedi.

( Zokomov | 2012. 02. 10., p – 07:54 )

Az Android SDK dokumentáció szerintem nagyon rendben van.

Az SDK alatt letölthetőek az SDK komponensek, pluginek, eszközmeghajtók és más fejlesztői eszközök.

A Dev Guide részletes magyarázatot szolgáltat az alkalmazás keretrendszerről, a fejlesztésről, publikálásól, értékesítésről stb.

A Reference egy referencia, ami nélkülözhetetlen.

A Resources alatt vannak tutorialok, példakódok, cikkek stb.

( Hevi v | 2012. 02. 10., p – 10:59 )

Számomra a jó dokumentáció egyik ismérve, hogy a releváns tartalom első oldalon jön Google keresésre :)

Nagyon megkönnyíti az utánanézést.

( saxus | 2012. 02. 10., p – 11:00 )

- Leírja a cucc mögöttes konpcepcióját, felépítését (akár ábrákat), meg úgy eleve, hogy mi az, mire jó mire nem
- Van használatba vételhez szükséges leírás
- Általános use-case-kra ad példát, howtut, stb.
- Tartalmaz API dokumentációt
- Az API doc nem merül ki a egy egysoros függvény előtti kommentből, hanem rendesen le van dokumentálva (hibás működés is, valamint ha változik a verzióval (pl. bővül), akkor azok is fel vannak tüntetve. Opcionálisan példakód.)

MSDN meg nem tudom kinek átláthatatlan, de az nem biztos, hogy IT-ben kellene, hogy dolgozzon...

----------------
Lvl86 Troll

C#-os MSDN-nél nekem kicsit fura, hogy pl. a metódusok visszatérési értékét nem írja ki akkor, amikor egy osztály doksiját nézed. (http://msdn.microsoft.com/en-us/library/system.string%28v=vs.95%29.aspx) Kiválasztott metódus részletesebb leírásánál már persze ott van. Javanál viszont elsőre is látod. (http://docs.oracle.com/javase/6/docs/api/java/lang/String.html)

( crystal88 | 2012. 02. 11., szo – 12:55 )

- architekturális áttekintés, ábrákkal
- jó API doksi
- példák, howto-k, best practice-ek

( Aadaam v | 2012. 02. 11., szo – 13:10 )

Klasszikus API-doksi (tehat generalt) -bol a legjobb az openfire -e amivel eddig talalkoztam - http://www.igniterealtime.org/builds/openfire/docs/latest/documentation…

Ez volt kb. az egyetlen kod, aminek megbocsatottam a javadoc-okat.

Altalaban ugy vagyok vele, ha meglatok egy ilyet:


/** persists the CV record sent to the professional specified by ID.
* returns true if succeeded
* @param JobUploaderID The ID of the job uploader
* @return boolean
*/
public boolean saveAttachment(int JobUploaderID){...

Akkor alapvetoen az jut eszembe, hogy ha azt csinalja, nevezd el annak, ill. tanulj meg exceptionoket dobni, meg azonos neveket hasznalni.

A JavaDoc sok helyet foglal, es olyan szinten kell ertelmesnek lenni, mint az OpenFire doksijanak, hogy megerje. Kulonben en speciel elkezdem olvasni a forrast.

Nagyon szeretem az atnezodolgokat, sajna a mai programozok tobbsege nem tud olvasni (aminek egy sajnalatos mellekkovetkezmenye, hogy irni se, plane kodot), a PHP kodpeldak mondjuk tenyleg sokat tudnak segiteni az embereknek, igaz, sajna abbol esznelkuli copy-pasta lesz sokaknak, de hat ez mar nem az API doksi iro baja.

GMaps doksit is erdemes megnezni.

Playgroundok se rossz dolgok dinamikus rendszereknel, vagy olvashato tesztek (Jasmine pl), helyzetfuggo.

A konkret program (API) feladataihoz kepest egyszerubb lenne ajanlani.

GMaps API doksira nezz ra esetleg.

API referencianak jo, de meg mindig ugyanott tartunk: ez _nem_ SDK.

(Az megvan, hogy az SDK az software developer kit-et jelent, amihez nem csak egy lib + API doksi tartozik, hanem sok esetben segedprogramok - amihez szinten tartozik kezikonvy -, fajlformatumok, kommunikacios protokolok - amihez jo lenne valami leiras es meg csillio mas dolog.

Jo pelda erre a Half-Life SDK: van ott a forraskodon kivul modellkonvertalashoz, texturacsomag kesziteshez, palyaszerkeszteshez kezikonyv, program. API doc nem is volt igazabol a HL1-hez, bar azert a Source Engine-hez vannak mar cikkek jocskan...)

----------------
Lvl86 Troll

Oks, de sok esetben az SDK doksi API resze sem ilyen reszletes, mint ez. Ha meg mar ilyen reszletes, akkor mar valoszinuleg a tobbi doksi is jo. De ez egy iranyado minden doksinak, hogy kellenek bele magyarazatok, reszletek, hasznalati peldak, es nem csak az API, de az utility doksiba is, ha van.

A UM meg mar egy egesz mas terulet, de azt nem is a fejlesztok irjak.
-- 

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. | Gentoo Portal