On 25/08/2011, Hans-Peter Diettrich wrote: >> >> http://opensoft.homeip.net:8080/tiopf/core/fpdoc.css > > I'm not sure how to use that file. Shall it replace the css in the > docs/lcl folder, before compiling the docs?
You can simply copy it over the existing .css file after you generated the HTML output. By default fpdoc doesn't supply a fpdoc.css file as far as I know. Neither does it generate one in the HTML output. Well, this was last time I checked, things might have changed in recent months. >> >> http://opensoft.homeip.net:8080/tiopf/core/tiobject/tperobjectstate.html > > Like that, but it looks as if the declaration in the source code > contains the description. If you are referring to the description in the tiOPF source code - those are NOT used by fpdoc at all. FPDoc only looks at what is inside the related XML files (like the sample I posted). The tiOPF project used to use pasdoc many years ago as the class document generator. We simply haven't deleted those messy inline comments yet - it's on a low priority todo list. >> <element name="TPerObjectState"> >> <short>The possible states of a TtiObject descendant in memory</short> >> <descr><printshort id="TPerObjectState"/>.</descr> >> </element> > > I don't fully understand the use of <printshort> here. Does it simply > duplicate the short description of the same entry? Yes, that is the style I prefer. The short description is a short one line comment - usable in HTML ouput like a class interface. The <descr> is then the full description of the feature - starting with the short description, and continuing from there. Sometimes the information in the short description is enough detail, or contains important details, so that's why I duplicate it with the <printshort> tag. >> <element name="TPerObjectState.posEmpty"> >> <short>The object has been created, but not filled with data from the >> DB</short> >> </element> > > A short description may be useful here, but sometimes a longer > description is required. Then I see several solutions: This is a limitation of fpdoc's HTML output writer (and maybe some other output formats too). The fpdoc HTML output writer doesn't used the <descr> element anywhere for enum elements documentation, only the <short> element is used. For the enum type itself, both <short> and <descr> are used. > Something like you provided above. Sample code for describing various > element types, e.g. procedures (with parameters), enums (with members), > properties... The tiTokenLibrary unit in tiOPF uses (I think) all features of fpdoc. Images, unit overview, long and short description for enum types, class declaration, method parameter descriptions, example code etc. http://opensoft.homeip.net:8080/tiopf/core/titokenlibrary/index.html It is a small unit, so it might make for a good example of fpdoc usage. Note: I haven't generated tiOPF's class documentation in any other fpdoc format (HTML only), so I don't know how those other output writers handle images. The tags I used in the description section of the XML file are all fpdoc tags though - I never use HTML specific tags embedded in such descriptions. So in theory all fpdoc output writers should handle the XML documentation file correctly. -- Regards, - Graeme - _______________________________________________ fpGUI - a cross-platform Free Pascal GUI toolkit http://fpgui.sourceforge.net -- _______________________________________________ Lazarus mailing list [email protected] http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
