Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / fpc-devel / 2008-11

Documentation for FCL files not already in the FreePascal docs

8 messages · 4 people · –

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Chris Kirkpatrick

I am trying to provide documentation for the LCL (as .xml files using FPDoc and tools in the Lazarus IDE).

In the unit Graphics, there are several Components that inherit properties and methods from components and units in the FCL, including FPImgCmn, FPImage, FPCanvas,
FPReadPNG, FPWritePNG,
FPReadBMP, FPWriteBMP,
FPReadPNM, FPWritePNM,
FPReadJpeg, FPWriteJpeg.

For example, when trying to write definitions for TPen, TBrush, TCanvas etc, I am constantly finding references to TFPCanvas, TFPBrush and other components in FPCanvas.

As far as I can see, there are no documentation files for these Units, and when I try to create a documentation entry I get an error message (see attached).

I need advice: either we need documentation files created by the FPC developers, or I need to try to create documentation files using MakeSkel and then submit them as patches (unless the FPC team are prepared to allow me to commit changes to the Docs directory in SVN).

Please advise.
Regards - Chris

Reply by email

Michael Van Canneyt
to Chris Kirkpatrick
Chris Kirkpatrick wrote 21 lines
I am trying to provide documentation for the LCL (as .xml files using FPDoc and tools in the Lazarus IDE). In the unit Graphics, there are several Components that inherit properties and methods from components and units in the FCL, including FPImgCmn, FPImage, FPCanvas, FPReadPNG, FPWritePNG, FPReadBMP, FPWriteBMP, FPReadPNM, FPWritePNM, FPReadJpeg, FPWriteJpeg. For example, when trying to write definitions for TPen, TBrush, TCanvas etc, I am constantly finding references to TFPCanvas, TFPBrush and other components in FPCanvas. As far as I can see, there are no documentation files for these Units, and when I try to create a documentation entry I get an error message (see attached). I need advice: either we need documentation files created by the FPC developers, or I need to try to create documentation files using MakeSkel and then submit them as patches (unless the FPC team are prepared to allow me to commit changes to the Docs directory in SVN).

You can always create the files and use them locally.

As you know, policy is not to include docs unless the unit is fully documented.

Michael.

Reply by email

Vincent Snijders
to Michael Van Canneyt
Michael Van Canneyt wrote 30 lines
On Wed, 5 Nov 2008, Chris Kirkpatrick wrote: > I am trying to provide documentation for the LCL (as .xml files using FPDoc > and tools in the Lazarus IDE). > > In the unit Graphics, there are several Components that inherit properties and > methods from components and units in the FCL, including > FPImgCmn, FPImage, FPCanvas, > FPReadPNG, FPWritePNG, > FPReadBMP, FPWriteBMP, FPReadPNM, FPWritePNM, FPReadJpeg, FPWriteJpeg. > > For example, when trying to write definitions for TPen, TBrush, TCanvas etc, I > am constantly finding references to TFPCanvas, TFPBrush and other components > in FPCanvas. > > As far as I can see, there are no documentation files for these Units, and > when I try to create a documentation entry I get an error message (see > attached). > > I need advice: either we need documentation files created by the FPC > developers, or I need to try to create documentation files using MakeSkel and > then submit them as patches (unless the FPC team are prepared to allow me to > commit changes to the Docs directory in SVN). You can always create the files and use them locally. As you know, policy is not to include docs unless the unit is fully documented.

Can you create a branch for Chris to work on it? Or should we keep those partially (because of work in progress) documented in the Lazarus repository and then you can send patches, if you are working on it, but are not yet finished.

Vincent

Reply by email

Michael Van Canneyt
to Vincent Snijders
Vincent Snijders wrote 42 lines
Michael Van Canneyt schreef: > > On Wed, 5 Nov 2008, Chris Kirkpatrick wrote: > > > I am trying to provide documentation for the LCL (as .xml files using > > FPDoc > > and tools in the Lazarus IDE). > > > > In the unit Graphics, there are several Components that inherit properties > > and > > methods from components and units in the FCL, including > > FPImgCmn, FPImage, FPCanvas, > > FPReadPNG, FPWritePNG, > > FPReadBMP, FPWriteBMP, FPReadPNM, FPWritePNM, FPReadJpeg, FPWriteJpeg. > > > > For example, when trying to write definitions for TPen, TBrush, TCanvas > > etc, I > > am constantly finding references to TFPCanvas, TFPBrush and other > > components > > in FPCanvas. > > > > As far as I can see, there are no documentation files for these Units, and > > when I try to create a documentation entry I get an error message (see > > attached). > > > > I need advice: either we need documentation files created by the FPC > > developers, or I need to try to create documentation files using MakeSkel > > and > > then submit them as patches (unless the FPC team are prepared to allow me > > to > > commit changes to the Docs directory in SVN). > > You can always create the files and use them locally. > > As you know, policy is not to include docs unless the unit is fully > documented. > Can you create a branch for Chris to work on it? Or should we keep those partially (because of work in progress) documented in the Lazarus repository and then you can send patches, if you are working on it, but are not yet finished.

I prefer the latter option.

Michael.

Reply by email

Vincent Snijders
to Michael Van Canneyt
Michael Van Canneyt wrote 24 lines
On Wed, 5 Nov 2008, Vincent Snijders wrote: > Michael Van Canneyt schreef: >> On Wed, 5 Nov 2008, Chris Kirkpatrick wrote: >> >>> I need advice: either we need documentation files created by the FPC >>> developers, or I need to try to create documentation files using MakeSkel >>> and >>> then submit them as patches (unless the FPC team are prepared to allow me >>> to >>> commit changes to the Docs directory in SVN). >> You can always create the files and use them locally. >> >> As you know, policy is not to include docs unless the unit is fully >> documented. >> > Can you create a branch for Chris to work on it? Or should we keep those > partially (because of work in progress) documented in the Lazarus repository > and then you can send patches, if you are working on it, but are not yet > finished. I prefer the latter option.

Chris, feel free to add these new xml docs to a new directory: http://svn.freepascal.org/svn/lazarus/trunk/docs/xml/fcl

I will try to incorporate these files in the nightly doc builds, either by patching the Makefile in fpcdocs or by creating new shell script based on the html/build_lcl_html.sh script.

Vincnet

Reply by email

Vincent Snijders
to Christopher Kirkpatrick
Christopher Kirkpatrick wrote 14 lines
On Wed, 05 Nov 2008 15:44:59 +0100 Vincent Snijders wrote: >> Chris, feel free to add these new xml docs to a new > directory: > http://svn.freepascal.org/svn/lazarus/trunk/docs/xml/fcl > > I will try to incorporate these files in the nightly doc builds, > either by patching the Makefile in fpcdocs or by creating new shell > script based on the html/build_lcl_html.sh script. > Thank you very much, Vincent. That will be most helpful.

I have updated the build script for the docs are sourceforge. See http://lazarus-ccr.sourceforge.net/fpcdoc/fcl/fpcanvas/index.html and http://lazarus-ccr.sourceforge.net/fpcdoc/fcl/fpimage/index.html

I got the following errors, but I don't know why:
[#fcl.FPimage.TFPCustomImage.Progress] Invalid description (illegal XML element: "printshort")
[#fcl.FPimage.TFPCustomImageHandler.Progress] Invalid description (illegal XML element: "printshort")

I just copy the lazarus/docs/xml/fcl files into fpcdocs dir and have adapted the Makefile.fpc as in attached patch.

Chris, if you add a new file, I need to adapt the Makefile.fpc. If I don't notice or forget to make that change, feel free to send me a notice.

html.bzip2 and chm with these new docs follow soon.

Vincent

Reply by email

Chris Kirkpatrick
to Vincent Snijders
Vincent Snijders wrote 11 lines
I have updated the build script for the docs are sourceforge. See http://lazarus-ccr.sourceforge.net/fpcdoc/fcl/fpcanvas/index.html and http://lazarus-ccr.sourceforge.net/fpcdoc/fcl/fpimage/index.html I got the following errors, but I don't know why: [#fcl.FPimage.TFPCustomImage.Progress] Invalid description (illegal XML element: "printshort") [#fcl.FPimage.TFPCustomImageHandler.Progress] Invalid description (illegal XML element: "printshort")

I guess the 'printshort' is a remnant from where a short description has been removed and replaced by a link to an ancestor file; if there is no short description, printshort has the argument '' which it doesn't like. I'll try to find the offending entry and remove it. Regards - Chris

Reply by email