From feebca5f5bedc838d64cffa501c770245d31631f Mon Sep 17 00:00:00 2001 From: dodi Date: Tue, 20 Sep 2011 04:25:48 +0000 Subject: [PATCH] Docs: add some scripts and StyleGuide git-svn-id: trunk@32433 - --- .gitattributes | 3 ++ docs/xml/README.txt | 2 + docs/xml/StyleGuide.txt | 117 ++++++++++++++++++++++++++++++++++++++++ docs/xml/mkhtml.bat | 4 ++ docs/xml/updateXML.bat | 4 ++ 5 files changed, 130 insertions(+) create mode 100644 docs/xml/StyleGuide.txt create mode 100644 docs/xml/mkhtml.bat create mode 100644 docs/xml/updateXML.bat diff --git a/.gitattributes b/.gitattributes index 11bf596bf6..ce640a1fba 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2979,6 +2979,7 @@ docs/images/laztitle.svg -text svneol=native#image/svg%2Bxml docs/index.html svneol=native#text/html docs/lazdoc.css svneol=native#text/plain docs/xml/README.txt svneol=native#text/plain +docs/xml/StyleGuide.txt svneol=native#text/plain docs/xml/fcl/bmpcomn.xml svneol=native#text/xml docs/xml/fcl/clipping.xml svneol=native#text/xml docs/xml/fcl/ellipses.xml svneol=native#text/xml @@ -3164,11 +3165,13 @@ docs/xml/lcl/utf8process.xml svneol=native#text/plain docs/xml/lcl/utrace.xml svneol=LF#text/xml eol=lf docs/xml/lcl/wscontrols.xml svneol=native#text/plain docs/xml/lcl/xmlpropstorage.xml svneol=LF#text/xml eol=lf +docs/xml/mkhtml.bat svneol=native#text/plain docs/xml/multi_makeskel.pl svneol=native#text/plain docs/xml/rtl/README.txt svneol=native#text/plain docs/xml/rtl/classes.xml svneol=native#text/xml docs/xml/rtl/system.xml svneol=native#text/xml docs/xml/rtl/sysutils.xml svneol=native#text/xml +docs/xml/updateXML.bat svneol=native#text/plain examples/SynEdit/Completion/SynCompletionSample.ico -text examples/SynEdit/Completion/SynCompletionSample.lpi svneol=native#text/plain examples/SynEdit/Completion/SynCompletionSample.lpr svneol=native#text/pascal diff --git a/docs/xml/README.txt b/docs/xml/README.txt index b2a001639c..a35b02d182 100644 --- a/docs/xml/README.txt +++ b/docs/xml/README.txt @@ -20,6 +20,8 @@ makeskel --update --package=lcl --input="..\..\lcl\forms.pp" --descr=lcl\forms.x To create a new file use: makeskel --package=lcl --input="..\..\lcl\forms.pp" --output=lcl\forms.xml +See also: StyleGuide.txt + -------------------------------------------------------------------------------- Examples for gtk interface: diff --git a/docs/xml/StyleGuide.txt b/docs/xml/StyleGuide.txt new file mode 100644 index 0000000000..f9486bc5f9 --- /dev/null +++ b/docs/xml/StyleGuide.txt @@ -0,0 +1,117 @@ +Some suggestions for documentation writers +========================================== +By DoDi + +Content +------- + +Have a look at the generated (HTML) docs. +FPDoc inserts a lot of information and links automatically. Don't bother with +adding extra links in text and . + +Add short descriptions to procedure arguments and function results, these are +shown in the copied declaration. The visibility comments can be removed for +arguments or enum elements, so that it will become easier to spot related items. + +Add long parameter descriptions if required, don't put these into the procedure +description. This allows for links to this description! + +Don't duplicate descriptions, use links to already existing descriptions. + +Consider the later reader. +Public items (methods...) are for use by coders, the short description can read like +"Use ... to ..." +Other items can be hit during coding or debugging, the short description should +provide meaningful information in the FPDoc editor or in the popup hints. Avoid +excess decoration, e.g.: +"Returns ..." +instead of +"ThisItem - reads the FItem field." + +Don't describe the obvious. +Constructors and destructors deserve special descriptions only, when they have +special parameters. Even then short notes on the parameters are sufficient, +because FPDoc inserts the inherited descriptions for empty descriptions. + +Don't describe overridden methods again. +FPDoc inserts the inherited description (at least in HTML output). + + +Style +----- + +Write sentences, terminated with a full stop (dot). +Unterminated descriptions should be revised by (native) English speakers. + +Everybody can add revision marks. +I use brackets for now, to indicate passages with questionable content: +[?] unclear wording, possibly wrong. Long: [what's this?] +[???] unreadable or definitely wrong description. +[~] somebody else should make this proper and nice English. +[!] Incompatible or wrong implementation, e.g. [Delphi incompatible!] + + +XML Syntax +---------- +Copy and run mkhtml.bat in docs\html\, I cannot commit to that directory :-( + +Use mkhtml.bat for quick compilation of single unit documentation, and fix the +reported errors before committing. E.g. +> mkthml controls pp +The result is stored in the html\test directory. It's a good idea to delete this +directory before, because FPDoc does not always update existing files properly! +> mkthml grids pas >log.txt +stores the error log in log.txt, which can be loaded into the IDE, to simplify +searching for missing references and tracking of fixed errors. + +Common errors result from a mix of plain text with paragraphs, remarks, pre, +code, lists or tables. Then you get "#text" error messages for such dangling text. + +"Warning: Target ID of is unknown: ..." often result from protected items, +which are not normally part of the RTL and FCL documentation. Try to link to a +public property instead, if one exists. + +Unmatched beginning and ending tags are hard to find. It often helps to insert +an dummy tag of the missing or excess type, somewhere in the xml source, run again +and narrow down the exact location by a binary search. + + +Sync with the source +-------------------- +Use updateXML.bat to find removed or missing items. E.g. +> updateXML controls pp +creates controls.upd.xml, containing added or otherwise missing elements. + +Check the console output for "... no longer used" messages, and remove these +items from the XML file. Check the source code for only renamed items, and update +only the name field, in order to preserve already existing documentation. + +The *.upd.xml file contains added or renamed items. Find a good location where to +insert added elements. New subroutine argument should be added just after the +procedure element, while changed argument names can be updated in place. + +Take the chance to compare the entries with the descriptions in the source code. +But be careful with differing descriptions, and check the implementation as well, +before copying possibly outdated comments from the source code over more current docs! +Hereby it can help a lot to rearrange the entries, for easy comparison with the +declarations in the source code. + +Multiple editor windows can help in the comparison of source and xml files, +eventual log files or upd files. Obviously misplaced items (arguments!) can be +moved into an dummy xml file, then moved back from there to their proper locations. +Don't search for whole words in the xml files, because this will *not* find the +quoted procedure names etc.! + + +The following applies in detail to HTML output format. +------------------------------------------------------ + +Use links to identical items, this simplifies the document maintenance a lot. +(See TDragObject descendants and TDrag...Event handlers) + + +Describe properties only once, and link fields, getters and setters to the +property description: + + + diff --git a/docs/xml/mkhtml.bat b/docs/xml/mkhtml.bat new file mode 100644 index 0000000000..70deeaffef --- /dev/null +++ b/docs/xml/mkhtml.bat @@ -0,0 +1,4 @@ +rem Call fpdoc for the given LCL module <%1> . <%2> +rem PATH=\repos\fpc-2.5.trunk\utils\fpdoc +rem del /S /Q test +fpdoc --import=\LazDocs\rtl.xct,../rtl/ --import=\LazDocs\fcl.xct,../fcl/ --import=\LazDocs\lcl.xct,../test/ --package=lcl --output=test --input="..\..\lcl\%1.%2 -Fi..\..\lcl\include" --descr=..\xml\lcl\%1.xml --format=html --css-file=fpdoc.css diff --git a/docs/xml/updateXML.bat b/docs/xml/updateXML.bat new file mode 100644 index 0000000000..5010d6d1ef --- /dev/null +++ b/docs/xml/updateXML.bat @@ -0,0 +1,4 @@ +rem Call makeskel for the given LCL module <%1> . <%2> +rem PATH=\repos\fpc-2.5.trunk\utils\fpdoc +makeskel --package=lcl --input="..\..\lcl\%1.%2 -Fi..\..\lcl\include" --descr=lcl\%1.xml --update --output=lcl\%1.upd.xml +