Re: [fpc-devel] fpdoc inherited entries
On Sun, 17 Feb 2008, Mattias Gaertner wrote: In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries. Comments? This is in mantis as a feature request, but it is not easy to implement. Feel free to do a proposition. I'll then do the implementation :-) Michael. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries. Comments? Make it mandatory to flag such properties if you want to use this feature. Nobody is interested in all inbetween properties and symbols. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
Zitat von Michael Van Canneyt [EMAIL PROTECTED]: On Sun, 17 Feb 2008, Mattias Gaertner wrote: In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries. Comments? This is in mantis as a feature request, but it is not easy to implement. I added a button to the IDE built in fpdoc editor to automatically create a 'see also' link to the next documented ancestor entry. Feel free to do a proposition. I'll then do the implementation :-) That's an amazing offer. fpdoc already knows the ancestor classes. So it should be possible to find out the ancestor property/method/variable, right? (It's ok if the overridden method search is not 100% perfect) If yes, then it might be possible to traverse through all ancestors and find the next existing short description, right? Mattias ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
On Mon, 18 Feb 2008, Mattias Gärtner wrote: Zitat von Michael Van Canneyt [EMAIL PROTECTED]: On Sun, 17 Feb 2008, Mattias Gaertner wrote: In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries. Comments? This is in mantis as a feature request, but it is not easy to implement. I added a button to the IDE built in fpdoc editor to automatically create a 'see also' link to the next documented ancestor entry. Feel free to do a proposition. I'll then do the implementation :-) That's an amazing offer. fpdoc already knows the ancestor classes. So it should be possible to find out the ancestor property/method/variable, right? (It's ok if the overridden method search is not 100% perfect) The problem is that you may or may not have the definition (and corresponding page) in memory. If the parent def (and doc) is not in memory, you don't know whether a page is available or not. If yes, then it might be possible to traverse through all ancestors and find the next existing short description, right? In theory, yes. Then you need to decide what to do: - Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho) - do not generate a page but In the 'Property/methods/Class overview' of TChild, refer to TParent.property whenever TChild.Property is not documented. In the latter case, pressing F1 on TChild.Property will refer to a non-existing page. Michael.___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
Zitat von Michael Van Canneyt [EMAIL PROTECTED]: On Mon, 18 Feb 2008, Mattias Gärtner wrote: Zitat von Michael Van Canneyt [EMAIL PROTECTED]: On Sun, 17 Feb 2008, Mattias Gaertner wrote: In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries. Comments? This is in mantis as a feature request, but it is not easy to implement. I added a button to the IDE built in fpdoc editor to automatically create a 'see also' link to the next documented ancestor entry. Feel free to do a proposition. I'll then do the implementation :-) That's an amazing offer. fpdoc already knows the ancestor classes. So it should be possible to find out the ancestor property/method/variable, right? (It's ok if the overridden method search is not 100% perfect) The problem is that you may or may not have the definition (and corresponding page) in memory. If the parent def (and doc) is not in memory, you don't know whether a page is available or not. How do the links to the ancestor classes work? If yes, then it might be possible to traverse through all ancestors and find the next existing short description, right? In theory, yes. :) Then you need to decide what to do: - Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho) - do not generate a page but In the 'Property/methods/Class overview' of TChild, refer to TParent.property whenever TChild.Property is not documented. In the latter case, pressing F1 on TChild.Property will refer to a non-existing page. The final presentation whether fpdoc creates a 'see also' link OR copies the content OR refers directly is a second step. First fpdoc must gather some data: It should only refer, iff the TChild.Property is not documented (= has no short description) and iff there is a documented TParent.Property, where TParent does not need to be the direct ancestor. For example TButton.Caption should not refer to TCustomButton.Caption nor TWinControl.Caption, but to TControl.Caption. Mattias ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
On Mon, 18 Feb 2008, Mattias Gärtner wrote: Zitat von Michael Van Canneyt [EMAIL PROTECTED]: On Mon, 18 Feb 2008, Mattias Gärtner wrote: Zitat von Michael Van Canneyt [EMAIL PROTECTED]: On Sun, 17 Feb 2008, Mattias Gaertner wrote: In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries. Comments? This is in mantis as a feature request, but it is not easy to implement. I added a button to the IDE built in fpdoc editor to automatically create a 'see also' link to the next documented ancestor entry. Feel free to do a proposition. I'll then do the implementation :-) That's an amazing offer. fpdoc already knows the ancestor classes. So it should be possible to find out the ancestor property/method/variable, right? (It's ok if the overridden method search is not 100% perfect) The problem is that you may or may not have the definition (and corresponding page) in memory. If the parent def (and doc) is not in memory, you don't know whether a page is available or not. How do the links to the ancestor classes work? Through a complicated search mechanism :-) If yes, then it might be possible to traverse through all ancestors and find the next existing short description, right? In theory, yes. :) Then you need to decide what to do: - Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho) - do not generate a page but In the 'Property/methods/Class overview' of TChild, refer to TParent.property whenever TChild.Property is not documented. In the latter case, pressing F1 on TChild.Property will refer to a non-existing page. The final presentation whether fpdoc creates a 'see also' link OR copies the content OR refers directly is a second step. First fpdoc must gather some data: It should only refer, iff the TChild.Property is not documented (= has no short description) and iff there is a documented TParent.Property, where TParent does not need to be the direct ancestor. For example TButton.Caption should not refer to TCustomButton.Caption nor TWinControl.Caption, but to TControl.Caption. I am more in favour of adding a new attribute to allow more control by the documentor: element name=TButton.Caption link=TControl.Caption/ It has the advantage of being faster as well: the documenting process can use some speedup, it gets slower by the day. The disadvantage is that you must fill it in manually - although a simple button in the editor can take care of that: - fill this property for the current element, or - for all elements with fill your favorite recipe here fill the closest ancestor. Michael.___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
On Mon, 18 Feb 2008, Felipe Monteiro de Carvalho wrote: On Feb 18, 2008 12:51 PM, Michael Van Canneyt [EMAIL PROTECTED] wrote: Then you need to decide what to do: - Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho) Why is creating a link from TChild.Property to TParent.Property a bad thing? Because you don't need the TChild.Property page at all. There should not be a link to TChild.Property anywhere. All links should always be to TParent.property. In the overview page: Class TChild ... Properties ... Property MyProperty; -- link to TParent.MyProperty, NOT to TChild.Property AFAIK, if you use Doc-o-Mactic it will do exactly that. Delphi help also works like that. In fact, I don't know any example of a source code documenting system that copyes the same text on several places for the same function. Delphi uses the second mechanism which I proposed (the not-braindead-one). In the 'TFileStream Methods', just click on TFileStream.WriteBuffer, under 'Derived from TStream', and it takes you to to TStream.WriteBuffer. The braindead one would take you to a mostly empty page TFileStream.WriteBuffer with a small clickable text 'This method is documented in TStream.WriteBuffer.' Michael. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
On Feb 18, 2008 12:51 PM, Michael Van Canneyt [EMAIL PROTECTED] wrote: Then you need to decide what to do: - Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho) Why is creating a link from TChild.Property to TParent.Property a bad thing? AFAIK, if you use Doc-o-Mactic it will do exactly that. Delphi help also works like that. In fact, I don't know any example of a source code documenting system that copyes the same text on several places for the same function. -- Felipe Monteiro de Carvalho ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
On Feb 18, 2008 2:17 PM, Michael Van Canneyt [EMAIL PROTECTED] wrote: Because you don't need the TChild.Property page at all. There should not be a link to TChild.Property anywhere. All links should always be to TParent.property. Ah ... ok, I misunderstood you. We have the same oppinion =) -- Felipe Monteiro de Carvalho ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
Zitat von Michael Van Canneyt [EMAIL PROTECTED]: [...] The problem is that you may or may not have the definition (and corresponding page) in memory. If the parent def (and doc) is not in memory, you don't know whether a page is available or not. How do the links to the ancestor classes work? Through a complicated search mechanism :-) Ok. If yes, then it might be possible to traverse through all ancestors and find the next existing short description, right? In theory, yes. :) Then you need to decide what to do: - Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho) - do not generate a page but In the 'Property/methods/Class overview' of TChild, refer to TParent.property whenever TChild.Property is not documented. In the latter case, pressing F1 on TChild.Property will refer to a non-existing page. The final presentation whether fpdoc creates a 'see also' link OR copies the content OR refers directly is a second step. First fpdoc must gather some data: It should only refer, iff the TChild.Property is not documented (= has no short description) and iff there is a documented TParent.Property, where TParent does not need to be the direct ancestor. For example TButton.Caption should not refer to TCustomButton.Caption nor TWinControl.Caption, but to TControl.Caption. I am more in favour of adding a new attribute to allow more control by the documentor: element name=TButton.Caption link=TControl.Caption/ It has the advantage of being faster as well: the documenting process can use some speedup, it gets slower by the day. The disadvantage is that you must fill it in manually - although a simple button in the editor can take care of that: - fill this property for the current element, or - for all elements with fill your favorite recipe here fill the closest ancestor. Ey, I thought I do the proposal and you do the implementation!? Now it seems I have to implement this 'for all elements' function in the editor. Will you implement the fpdoc part, that means the 'link' attribute, so that fpdoc does not create the TChild.Property pages and instead directly links to the linked page and update the fpdoc docs? Mattias ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] fpdoc inherited entries
On Mon, 18 Feb 2008, Mattias Gärtner wrote: It should only refer, iff the TChild.Property is not documented (= has no short description) and iff there is a documented TParent.Property, where TParent does not need to be the direct ancestor. For example TButton.Caption should not refer to TCustomButton.Caption nor TWinControl.Caption, but to TControl.Caption. I am more in favour of adding a new attribute to allow more control by the documentor: element name=TButton.Caption link=TControl.Caption/ It has the advantage of being faster as well: the documenting process can use some speedup, it gets slower by the day. The disadvantage is that you must fill it in manually - although a simple button in the editor can take care of that: - fill this property for the current element, or - for all elements with fill your favorite recipe here fill the closest ancestor. Ey, I thought I do the proposal and you do the implementation!? Hehe :) Now it seems I have to implement this 'for all elements' function in the editor. Clever twist of me, eh ? ;-) Will you implement the fpdoc part, that means the 'link' attribute, so that fpdoc does not create the TChild.Property pages and instead directly links to the linked page and update the fpdoc docs? Yes. It means a lot of checking, though, because all link id= references to TChild.Property must also be changed. If speed is affected, maybe I'll have to do some tricks in the search mechanism as well :( Michael.___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
[fpc-devel] fpdoc inherited entries
In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries. Comments? Mattias ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
