[Lazarus] FPDoc content and editor

Graeme Geldenhuys graemeg.lists at gmail.com
Fri Aug 26 09:43:09 CEST 2011


On 08/26/2011 07:07 AM, Hans-Peter Diettrich wrote:
> 
> A look at the HTML source reveals a reference to ../fpdoc.css. This 
> seems to be wrong, no .css in that directory.

I believe this was done to minimize duplication of the .css file. So
only one "top level" fpdoc.css file is needed, even for multiple
packages (eg: RTL, FCL, LCL etc).


> When copied to the 
> expected location, both your as well as the supplied fpcdoc.css cure the 
> excess whitespace.

Glad to here it has been fixed in the latest FPC then.


> @Michael: can you fix that, or do you need an bug report?


If you are referring to the double spaced HTML help located in (the
default URL's Lazarus IDE looks at):

 http://lazarus-ccr.sourceforge.net/docs/rtl/index.html
 http://lazarus-ccr.sourceforge.net/docs/fcl/index.html
 http://lazarus-ccr.sourceforge.net/docs/lcl/index.html

That is not Michael van Canneyt's work. It is the responsibility of the
person maintaining the lazarus-ccr project (I think Vincent is in charge
there). I suggest you file a Lazarus bug report or something.


>> 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 Declaration sections look like copied from the source code, they 
> even include the source filename and line number of the declaration.

Yes I know fpdoc looks at the source code, but what I meant was that it
doesn't look at descriptions or comments in the source code. The only
"documentation" fpdoc uses, is from the XML files. So even though the
tiOPF project has duplicate documentation information in the XML and
source code, only the XML ones are used [by fpdoc].



> structure. I regularly shudder, when I read descriptions like:
> "Create initializes the local fields, then calls the inherited 
> constructor" :-(

Documentation is a slow and boring process! I am currently documenting
fpGUI units one by one. I take my hat off for the work Michael has done
with the RTL, FCL and PDF docs. That is an incredible amount of work
that doesn't just happen over night.

But I agree with your sentiment, good documentation is vital to any
project. The Lazarus project is seriously lacking in that department. At
to make matters worse for the Lazarus project, the documentation is
fragmented. Some on the wiki, some in source code, some in fpdoc XML etc.


Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/





More information about the Lazarus mailing list