S B

ScriptBasic Dokumentáció metodológia

Peter Verhás2002 április 23.

S B 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

S B 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

S B 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

S B 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

S B 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

S B 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

S B 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

S B 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

S B 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

S B 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ó

S B 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

S B Felhasználói dokumentáció

• NEM a fejlesztő készíti, külön szakma

S B 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

S B Mikor készül a dokumentáció

IDŐFUNRQ

FUNSP

SYSSP

ARCHD

SOURDTESTD

INSTDMAIND

USERG

Szerződés kötés Kódolás kezdete

S B 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ó

S B 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

S B Praktikusan: mi a TEXI 2/2

• @chapter @section @sub...subsection

• @code{}, @var{}, @option{}, @file{}, @b{}, @i{}

• @itemize/ @item / @end itemize

• @example / @end example

S B Praktikusan: Mi a jamal

{@define MAC/X/Y/Z=Macro text}

{#use esd}http://peter.verhas.com/progs/perl/jamal

jamal.plxxx.jam xxx

esd.pmesd.pmesd.pmesd.pmesd.pmesd.pm

*Embedded Source DocumentationVagy más csomag

S B TEXI generálás jamal forrásból

perl jamal.pl devguide.texi.jam

devguide.texi.jam

devguide.texi

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

jamal.pl

esd.pm

S B PDF, HTML, RTF... TEXI-ből

devguide.texi devguide.html

devguide_toc.html

devguide_1.1.html

devguide_toc.thtml

devguide_1.1.thtml

devguide.chm

t2h.pl

devguide.rtf

hhc.exe

tex.exe

devguide.pdfdevguide.ps

...

S B 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*/]]] ]]]

S B 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 ){/*noverbatimCUT*/

Miért =item és nem @item,Miért =H és nem @sectionMiért T<> és nem @code{}...

S B Függvény dokumentálás (példa) 2/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 ){/*noverbatimCUT*/

Itt kezdi a szöveg beemelését

@section

@itemize

@item

@code{LOGSTATE_DEAD}

@end itemize

@example@end example

Itt fejezi be a szöveg beemelését

S B 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)

S B

Köszönöm a figyelmet