Hello. On 01/04/16 15:08, Tom Hacohen wrote: > On 01/04/16 14:03, Stefan Schmidt wrote: >> stefan pushed a commit to branch master. >> >> http://git.enlightenment.org/core/efl.git/commit/?id=1a4674dfc835d1587c18d262a8658383ae00b749 >> >> commit 1a4674dfc835d1587c18d262a8658383ae00b749 >> Author: Stefan Schmidt <[email protected]> >> Date: Fri Apr 1 15:01:48 2016 +0200 >> >> ecore_timer: document properties >> >> Make sure that we actually document the property itself and not only >> the >> property methods. >> --- >> src/lib/ecore/ecore_timer.eo | 2 ++ >> 1 file changed, 2 insertions(+) >> >> diff --git a/src/lib/ecore/ecore_timer.eo b/src/lib/ecore/ecore_timer.eo >> index 99f30a8..781ef7f 100644 >> --- a/src/lib/ecore/ecore_timer.eo >> +++ b/src/lib/ecore/ecore_timer.eo >> @@ -14,6 +14,7 @@ class Ecore.Timer (Eo.Base) >> eo_prefix: ecore_obj_timer; >> methods { >> @property interval { >> + [[Interval the timer ticks on.]] >> set { >> [[Change the interval the timer ticks off. If set during >> a timer call, this will affect the next interval. >> @@ -27,6 +28,7 @@ class Ecore.Timer (Eo.Base) >> } >> } >> @property pending { >> + [[Pending time regarding a timer.]] >> get { >> [[Get the pending time regarding a timer.]] >> return: double; >> > The correct thing is to only document the property and just use a > language that would work for both set and get with any extra comments in > the set/get sections. We currently use the word "control" as a generic > set/get word, but I think "access" is actually better suited. > Alternatively you could do what you did and just describe the property, > without a verb at all, which is also great. We need to come up with a > convention.
Personally I would avoid access or control. It the noun we are describing and that we someone access or control the property is implicit with the set/get methods. This opinion is not set in stone though, just my current feelings. > Anyhow, in the interval case above you should have removed the "Change > the interval the timer ticks off." from the "set" documentation and only > left the extra comment about setting during a timer call. Changed it. regards Stefan Schmidt ------------------------------------------------------------------------------ Transform Data into Opportunity. Accelerate data analysis in your applications with Intel Data Analytics Acceleration Library. Click to learn more. http://pubads.g.doubleclick.net/gampad/clk?id=278785471&iu=/4140 _______________________________________________ enlightenment-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
