1 / 26

ScriptBasic Dokumentáció metodológia

ScriptBasic Dokumentáció metodológia. Peter Verh á s 2002 április 23. Tartalom. Dokumentációk általában Feladatok, ki mikor miért készíti Egy konkrét példa forrás-dokumentáció módszerre. Miért kell a dokumentáció. A dokumentáció nem WOM A dokumentációt emberek olvassák Információ

luz
Download Presentation

ScriptBasic Dokumentáció metodológia

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. ScriptBasic Dokumentáció metodológia Peter Verhás 2002 április 23.

  2. Tartalom • Dokumentációk általában • Feladatok, ki mikor miért készíti • Egy konkrét példa forrás-dokumentáció módszerre

  3. Miért kell a dokumentáció • A dokumentáció nem WOM • A dokumentációt emberek olvassák • Információ • Szerződés melléklet, jogi kötés

  4. Dokumentációk fajtája a projekt során • Tervezési dokumentációk • Funkcionális kívánalmak FUNRQ • Funkcionális specifikáció FUNSP • Rendszer terv SYSSP • Fejlesztői dokumentációk • Architektúra leírás ARCHD • Forrás kód dokumentáció SOURD • Tesztelési dokumentáció TESTD • Felhasználói dokumentáció • Installációs útmutató INSTD • Rendszer karbantartási útmutató MAIND • Felhasználói dokumentáció USERG

  5. Funkcionális kívánalmak • Megrendelő írja • Minden álma benne van • Nem feltétlenül megvalósítható • Nem precíz • Üzleti kívánalmakat fogalmaznak meg benne • Tiszta képet ad a projektről, hogy miért is kell, mik az üzleti feltételek

  6. Funkcionális specifikáció • A kívánalmak alapján • Kölcsönösen elfogadott • Precízen megfogalmazott • Nem túlspecifikált • Általában ez a szerződés melléklete • Definiálja, hogy MIT fejlesztünk

  7. Rendszer terv • Részletesen definiálja a HOGYAN-t • A fejlesztés során változhat • verzió kezelési kérdések • Ez alapján dolgoznak a fejlesztők

  8. Architektúra leírás • Általánosan leírja az architektúrát, hogy utána a projektbe bekapcsolódó fejlesztő el tudjon igazodni a forráskód dokumentációban • Gépek, adatbázisok, táblák, szoftver komponensek, kapcsolódások

  9. Forrás kód dokumentáció • Részben a forráskódban (megjegyzések, doc-string), részben maga a kód • Kódolási konvenciók

  10. Tesztelési dokumentáció • Belső vagy külső (termék átadás-átvétel) definíció • Tesztelési eljárások definíciója • Tesztek leírása, tesztelési eredmények

  11. Installációs útmutató • Fejlesztő készíti arról, hogy hogyan kell a rendszert az elkészített csomagból az éles rendszeren installálni • Dokumentáció tesztelése • Dok. Teszt. Dokumentáció

  12. Rendszer karbantartási útmutató • Fejlesztő készíti arról, hogy hogyan kell az installált rendszert kezelni • Adatmentése, visszaállítás • Archiválás • Teljesítmény mérés, skálázás, extrapoláció/trend analízis • Hibakezelés, riasztások • Naplózások

  13. Felhasználói dokumentáció • NEM a fejlesztő készíti, külön szakma

  14. Ki készíti a dokumentációt • Tervezési dokumentációk • Funkcionális kívánalmak ügyfél • Funkcionális specifikáció ügyfél/fejlesztő • Rendszer terv fejlesztő (ügyfél látja) • Fejlesztői dokumentációk • Architektúra leírás fejlesztő • Forrás kód dokumentáció fejlesztő • Tesztelési dokumentáció tesztelő • Felhasználói dokumentáció • Installációs útmutató fejlesztő/dokumentátor • Rendszer karbantartási fejlesztő/dokumentátor útmutató • Felhasználói dokumentáció dokumentátor

  15. Mikor készül a dokumentáció Kódolás kezdete Szerződés kötés TESTD SYSSP USERG SOURD IDŐ FUNRQ FUNSP ARCHD INSTD MAIND

  16. Forrás dokumentáció metodológia a ScriptBasic projektben • Alap formátum TEXI (GNU standard TeX macro csomag), jamal makrókkal • Konvertálható • PS, PDF minden nyomtatható formátum TeX-hel • HTML (egy fájl, fejezetenként) • CHM (compiled HTML) • RTF • INFO dokumentáció • Bármire konvertálható

  17. Praktikusan: mi a TEXI 1/2 TEXI fejléc \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename devguide @settitle ScriptBasic Users Guide @setchapternewpage odd @c %**end of header

  18. Praktikusan: mi a TEXI 2/2 • @chapter @section @sub...subsection • @code{}, @var{}, @option{}, @file{}, @b{}, @i{} • @itemize/ @item / @end itemize • @example / @end example

  19. Praktikusan: Mi a jamal {@define MAC/X/Y/Z=Macro text} {#use esd} http://peter.verhas.com/progs/perl/jamal xxx.jam jamal.pl xxx esd.pm esd.pm esd.pm esd.pm esd.pm esd.pm *Embedded Source Documentation Vagy más csomag

  20. TEXI generálás jamal forrásból perl jamal.pl devguide.texi.jam devguide.texi.jam jamal.pl basext.c builder.c buildnum.c cftc.c cftd.c command.c confpile.c conftree.c dynlolib.c epreproc.c errcodes.c execute.c expression.c filesys.c getopt.c hndlptr.c hookers.c httpd.c ipreproc.c lexer.c linkedmodules.c lmt_cio.c lmt_httpd.c lmt_none.c lmt_wx.c logger.c lsp.c match.c matchc.c memory.c modumana.c myalloc.c mygmtime.c mynotimp.c notimp.c options.c prepext.c reader.c report.c scriba.c sym.c syntax.c testalloc.c testconf.c thread.c uniqfnam.c esd.pm devguide.texi

  21. devguide_1.1.html devguide_1.1.thtml PDF, HTML, RTF... TEXI-ből devguide.texi t2h.pl devguide.html devguide.rtf devguide_toc.thtml devguide_toc.html tex.exe hhc.exe devguide.pdf devguide.ps ... devguide.chm

  22. esd csomag használata {#sep/[[[/]]]} [[[#use esd]]] [[[#esd::command 0 s{\@\@}{SAVEALLDOUBLESOBAKA}g]]] [[[#esd::command 0a s{\@}{\@\@}g]]] [[[#esd::command 0b s{\{}{\@\{}g]]] [[[#esd::command 0c s{\}}{\@\}}g]]] [[[#esd::command 0d s{\$}{\@\$}g]]] [[[#esd::command 1 s{\/\*FUNCTION\*\/}{\@example}]]] [[[#esd::command 2 s{\/\*noverbatim}{\@end example}]]] ... [[[@define SourceFile/FILE_NAME=[[[#esd::include ../../FILE_NAME /*POD CUT*/]]] ]]]

  23. Függvény dokumentálás (példa) 1/2 /*POD =H log_state() This function safely returns the actual state of the log. This can be: =itemize =item T<LOGSTATE_NORMAL> the log is normal state accepting log items =item T<LOGSTATE_SHUTTING> the log is currently performing shut down, it does not accept any log item =item T<LOGSTATE_DEAD> the log is shut down all files are closed =item T<LOGSTATE_SYNCHRONOUS> the log is synchronous accepting log items =noitemize /*FUNCTION*/ int log_state(ptLogger pLOG ){ /*noverbatim CUT*/ Miért =item és nem @item, Miért =H és nem @section Miért T<> és nem @code{} ...

  24. Függvény dokumentálás (példa) 2/2 Itt kezdi a szöveg beemelését /*POD =H log_state() This function safely returns the actual state of the log. This can be: =itemize =item T<LOGSTATE_NORMAL> the log is normal state accepting log items =item T<LOGSTATE_SHUTTING> the log is currently performing shut down, it does not accept any log item =item T<LOGSTATE_DEAD> the log is shut down all files are closed =item T<LOGSTATE_SYNCHRONOUS> the log is synchronous accepting log items =noitemize /*FUNCTION*/ int log_state(ptLogger pLOG ){ /*noverbatim CUT*/ @section @itemize @item @code{LOGSTATE_DEAD} @end itemize @end example @example Itt fejezi be a szöveg beemelését

  25. Néhány más forrásdokumentálási lehetőség • Java -> JavaDoc • Python -> docstring (LaTeX) • Doxigen • esd2html.pl (SB korábbi eszköze)

  26. Köszönöm a figyelmet

More Related