ScriptBasic Dokumentáció metodológia
description
Transcript of ScriptBasic Dokumentáció metodológia
![Page 1: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/1.jpg)
S B
ScriptBasic Dokumentáció metodológia
Peter Verhás2002 április 23.
![Page 2: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/2.jpg)
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
![Page 3: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/3.jpg)
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
![Page 4: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/4.jpg)
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
![Page 5: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/5.jpg)
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
![Page 6: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/6.jpg)
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
![Page 7: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/7.jpg)
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
![Page 8: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/8.jpg)
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
![Page 9: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/9.jpg)
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
![Page 10: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/10.jpg)
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
![Page 11: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/11.jpg)
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ó
![Page 12: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/12.jpg)
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
![Page 13: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/13.jpg)
S B Felhasználói dokumentáció
• NEM a fejlesztő készíti, külön szakma
![Page 14: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/14.jpg)
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
![Page 15: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/15.jpg)
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
![Page 16: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/16.jpg)
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ó
![Page 17: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/17.jpg)
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
![Page 18: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/18.jpg)
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
![Page 19: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/19.jpg)
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
![Page 20: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/20.jpg)
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
![Page 21: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/21.jpg)
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
...
![Page 22: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/22.jpg)
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*/]]] ]]]
![Page 23: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/23.jpg)
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{}...
![Page 24: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/24.jpg)
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
![Page 25: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/25.jpg)
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)
![Page 26: ScriptBasic Dokumentáció metodológia](https://reader033.fdocuments.net/reader033/viewer/2022050809/568152a2550346895dc0c776/html5/thumbnails/26.jpg)
S B
Köszönöm a figyelmet