I have been trying out the new functionality of LazDoc in the IDE, on
which Mattias Gaertner has been working very hard.
Although it is still incomplete, and has been the subject of several bug
reports, it has a number of useful features. One of these is the
facility to 'copy from inherited', ie if a property has been described
for an ancestor, the description can be pasted into the descendant's
documentation.
I have recently done this for the properties of TGroupBox and TComboBox
in StdCtrls.xml, pasting in the descriptions from TCustomGroupBox and
TCustomComboBox (or earlier ancestors such as TControl or TWinControl if
the property is described there).
It is very easy to use, but I believe we should not routinely use it
until we are very sure the description in the ancestor class is correct
and complete, because if we decide that the ancestor's description isn't
right and we have already made the copies, we will have to retrace our
steps and change all the descendants' properties as well.
I should therefore welcome some quality control on the work I (and
others) have done in writing descriptions for the components in the LCL.
I started with TControl and other primitive components in Controls.xml,
and worked through Graphics, Forms, Dialogs, and then into the
components that are actually visible in the IDE, in StdCtrls, ExtCtrls
and ComCtrls as well as Menus, and have recently started on Grids,
DBCtrls and DBGrids.
I tried to write the descriptions for the ancestors such as
TCustomXx before describing TXx. In general I have not provided
detailed descriptions for the child classes if the properties have been
described in the ancestors; the on-line help and LazDoc hinting facility
can trace the description back to the ancestor. We should wait until the
descriptions for the primitive classes are complete and correct before
pasting the descriptions into the visible components. (This will
ultimately be needed for completion of the LCL manual, to make it like
the RTL manual. At present, if a property is not described explicitly
for a component, it doesn't appear in the HTML documentation files).
I have also been concentrating on Public or Published properties, and
recognise that there is still a lot to be done on the Protected properties.
All comments are most welcome.
Regards - Chris
_
To unsubscribe: mail [EMAIL PROTECTED] with
"unsubscribe" as the Subject
archives at http://www.lazarus.freepascal.org/mailarchives
