inconsistency between property/operation and port definitions

Hey all, and especially Peter,

From a user point of view I don't like the difference in specification betwen
Property/Attribute/Cnstant/Operation and ports:

// for operation
double changeParameter(double f) { ... }
this->addOperation( "changeParameter", &MyTask::changeParameter, this, OwnThread)
.doc("Change a parameter, return the old value.")
.arg("New Value", "The new value for the parameter.");
and

//for properties
std::string param;
this->addProperty( "Param", param ).doc("Param Description");
this->addProperty( "Palue", value ).doc("Value Description");

While for ports:

// for ports
InputPort<double> inPort;
this->ports()->addPort( "inPort", inPort ).doc( "documentation" );

I would prefer to have the same syntax as for ports for operations,
properties, constants, and attributes.
I prefer this syntax since already from my header it is clear what are the
properties and operations.

Can you give me a clue why you decided on the above syntax?

Tinne

inconsistency between property/operation and port definitions

On Tuesday 11 January 2011 13:17:52 Tinne De Laet wrote:
> Hey all, and especially Peter,
>
> From a user point of view I don't like the difference in specification
> betwen Property/Attribute/Cnstant/Operation and ports:
>
>
> // for operation
> double changeParameter(double f) { ... }
> this->addOperation( "changeParameter", &MyTask::changeParameter, this,
> OwnThread) .doc("Change a parameter, return the old value.") .arg("New
> Value", "The new value for the parameter."); and
>
> //for properties
> std::string param;
> this->addProperty( "Param", param ).doc("Param Description");
> this->addProperty( "Palue", value ).doc("Value Description");
>
> While for ports:
>
> // for ports
> InputPort<double> inPort;
> this->ports()->addPort( "inPort", inPort ).doc( "documentation" );
>
> I would prefer to have the same syntax as for ports for operations,
> properties, constants, and attributes.
> I prefer this syntax since already from my header it is clear what are the
> properties and operations.
>
> Can you give me a clue why you decided on the above syntax?

Less syntax, less typing, less compilation errors. You need to change code at
more places when the signature of an operation changes. For ports, we couldn't
omit the InputPort<Foo> definition because of the read/write(Foo) methods we
need to access.

The 'old' syntax is still supported. So you can write:

&#10;//Header:&#10;Operation&lt;void(double)&gt; myOp1;&#10;&#10;//CPP file:&#10;// constructor initialisation list:&#10;  myOp1(&quot;name&quot;, &amp;Class::Foo, this)&#10;// constructor body:&#10;  provides()-&gt;addOperation(myOp1).doc(&quot;The foo operation&quot;);&#10;

I don't think using the old syntax is really what you miss. I think
automatically generating a doc-html-page for each component (similar info as
the 'ls' command of a TaskContext) would solve your 'requirements' better.
Similar on how ros generates documentation for each package.

Peter

inconsistency between property/operation and port definitions

On Tuesday 11 January 2011 13:37:09 Peter Soetens wrote:
> On Tuesday 11 January 2011 13:17:52 Tinne De Laet wrote:
> > Hey all, and especially Peter,
> >
> > From a user point of view I don't like the difference in specification
> > betwen Property/Attribute/Cnstant/Operation and ports:
> >
> >
> > // for operation
> > double changeParameter(double f) { ... }
> > this->addOperation( "changeParameter", &MyTask::changeParameter, this,
> > OwnThread) .doc("Change a parameter, return the old value.") .arg("New
> > Value", "The new value for the parameter."); and
> >
> > //for properties
> > std::string param;
> > this->addProperty( "Param", param ).doc("Param Description");
> > this->addProperty( "Palue", value ).doc("Value Description");
> >
> > While for ports:
> >
> > // for ports
> > InputPort<double> inPort;
> > this->ports()->addPort( "inPort", inPort ).doc( "documentation" );
> >
> > I would prefer to have the same syntax as for ports for operations,
> > properties, constants, and attributes.
> > I prefer this syntax since already from my header it is clear what are
> > the properties and operations.
> >
> > Can you give me a clue why you decided on the above syntax?
>
> Less syntax, less typing, less compilation errors. You need to change code
> at more places when the signature of an operation changes. For ports, we
> couldn't omit the InputPort<Foo> definition because of the read/write(Foo)
> methods we need to access.
>
> The 'old' syntax is still supported. So you can write:
>
> &#10;&gt; //Header:&#10;&gt; Operation&lt;void(double)&gt; myOp1;&#10;&gt; &#10;&gt; //CPP file:&#10;&gt; // constructor initialisation list:&#10;&gt;   myOp1(&quot;name&quot;, &amp;Class::Foo, this)&#10;&gt; // constructor body:&#10;&gt;   provides()-&gt;addOperation(myOp1).doc(&quot;The foo operation&quot;);&#10;&gt;
Thanks for pointing this one out!

This however does not solve the inconsistency ....
Would it not still make sense to this:

Property<double> value;
this->properties()->addProperty( "Palue", value ).doc("Value Description");

This only involves the extra typing of Property< >.
I just do this request because in the last couple of days at least 3 people in
the office have been struggling with this syntax difference: the above syntax
compiles (so as you claim indeed fewer compilation errors).... but then you
have a Property< Property<double> >, which is an unknown type in the
taskbrowser .. and you cannot use it afterwards...
very confusing .......

>
> I don't think using the old syntax is really what you miss.
> I think
> automatically generating a doc-html-page for each component (similar info
> as the 'ls' command of a TaskContext) would solve your 'requirements'
> better. Similar on how ros generates documentation for each package.
This is indeed on my wish list :) and would be great for documentation!

However, I still like to have an overview of my component interface just by
looking at the header of my component, that's why I prefer to declare the
Properties, Operations, Ports in my header ... (although this might seem old-
fashioned.)

Thanks,

Tinne

inconsistency between property/operation and port definitions

On Tuesday 11 January 2011 14:07:13 Tinne De Laet wrote:
> On Tuesday 11 January 2011 13:37:09 Peter Soetens wrote:
> > On Tuesday 11 January 2011 13:17:52 Tinne De Laet wrote:
> > > Hey all, and especially Peter,
> > >
> > > From a user point of view I don't like the difference in specification
> > > betwen Property/Attribute/Cnstant/Operation and ports:
> > >
> > >
> > > // for operation
> > > double changeParameter(double f) { ... }
> > > this->addOperation( "changeParameter", &MyTask::changeParameter, this,
> > > OwnThread) .doc("Change a parameter, return the old value.") .arg("New
> > > Value", "The new value for the parameter."); and
> > >
> > > //for properties
> > > std::string param;
> > > this->addProperty( "Param", param ).doc("Param Description");
> > > this->addProperty( "Palue", value ).doc("Value Description");
> > >
> > > While for ports:
> > >
> > > // for ports
> > > InputPort<double> inPort;
> > > this->ports()->addPort( "inPort", inPort ).doc( "documentation" );
> > >
> > > I would prefer to have the same syntax as for ports for operations,
> > > properties, constants, and attributes.
> > > I prefer this syntax since already from my header it is clear what are
> > > the properties and operations.
> > >
> > > Can you give me a clue why you decided on the above syntax?
> >
> > Less syntax, less typing, less compilation errors. You need to change
> > code at more places when the signature of an operation changes. For
> > ports, we couldn't omit the InputPort<Foo> definition because of the
> > read/write(Foo) methods we need to access.
> >
> > The 'old' syntax is still supported. So you can write:
> >
> > &#10;&gt; &gt; //Header:&#10;&gt; &gt; Operation&lt;void(double)&gt; myOp1;&#10;&gt; &gt; &#10;&gt; &gt; //CPP file:&#10;&gt; &gt; &#10;&gt; &gt; // constructor initialisation list:&#10;&gt; &gt;   myOp1(&quot;name&quot;, &amp;Class::Foo, this)&#10;&gt; &gt; &#10;&gt; &gt; // constructor body:&#10;&gt; &gt;   provides()-&gt;addOperation(myOp1).doc(&quot;The foo operation&quot;);&#10;&gt; &gt; &#10;&gt; &gt;
>
> Thanks for pointing this one out!
>
> This however does not solve the inconsistency ....
> Would it not still make sense to this:
>
> Property<double> value;
> this->properties()->addProperty( "Palue", value ).doc("Value Description");
>
> This only involves the extra typing of Property< >.
> I just do this request because in the last couple of days at least 3 people
> in the office have been struggling with this syntax difference: the above
> syntax compiles (so as you claim indeed fewer compilation errors).... but
> then you have a Property< Property<double> >, which is an unknown type in
> the taskbrowser .. and you cannot use it afterwards...
> very confusing .......

I agree that we must fix this case. I think the API you propose is fine and
should catch most cases of 'misuse'. I'm now first fixing the property
composition/decomposition bugs (when writing to a file), which must be fixed in
2.2.1 asap.

>
> > I don't think using the old syntax is really what you miss.
> > I think
> > automatically generating a doc-html-page for each component (similar info
> > as the 'ls' command of a TaskContext) would solve your 'requirements'
> > better. Similar on how ros generates documentation for each package.
>
> This is indeed on my wish list :) and would be great for documentation!
>
> However, I still like to have an overview of my component interface just by
> looking at the header of my component, that's why I prefer to declare the
> Properties, Operations, Ports in my header ... (although this might seem
> old- fashioned.)

I'm not against this, it's your code :-)

Peter

inconsistency between property/operation and port definitions

On Tuesday 11 January 2011 15:53:02 Peter Soetens wrote:
> On Tuesday 11 January 2011 14:07:13 Tinne De Laet wrote:
> > On Tuesday 11 January 2011 13:37:09 Peter Soetens wrote:
> > > On Tuesday 11 January 2011 13:17:52 Tinne De Laet wrote:
> > > > Hey all, and especially Peter,
> > > >
> > > > From a user point of view I don't like the difference in
> > > > specification betwen Property/Attribute/Cnstant/Operation and ports:
> > > >
> > > >
> > > > // for operation
> > > > double changeParameter(double f) { ... }
> > > > this->addOperation( "changeParameter", &MyTask::changeParameter,
> > > > this, OwnThread) .doc("Change a parameter, return the old value.")
> > > > .arg("New Value", "The new value for the parameter."); and
> > > >
> > > > //for properties
> > > > std::string param;
> > > > this->addProperty( "Param", param ).doc("Param Description");
> > > > this->addProperty( "Palue", value ).doc("Value Description");
> > > >
> > > > While for ports:
> > > >
> > > > // for ports
> > > > InputPort<double> inPort;
> > > > this->ports()->addPort( "inPort", inPort ).doc( "documentation" );
> > > >
> > > > I would prefer to have the same syntax as for ports for operations,
> > > > properties, constants, and attributes.
> > > > I prefer this syntax since already from my header it is clear what
> > > > are the properties and operations.
> > > >
> > > > Can you give me a clue why you decided on the above syntax?
> > >
> > > Less syntax, less typing, less compilation errors. You need to change
> > > code at more places when the signature of an operation changes. For
> > > ports, we couldn't omit the InputPort<Foo> definition because of the
> > > read/write(Foo) methods we need to access.
> > >
> > > The 'old' syntax is still supported. So you can write:
> > >
> > > &#10;&gt; &gt; &gt; //Header:&#10;&gt; &gt; &gt; Operation&lt;void(double)&gt; myOp1;&#10;&gt; &gt; &gt; &#10;&gt; &gt; &gt; //CPP file:&#10;&gt; &gt; &gt; &#10;&gt; &gt; &gt; // constructor initialisation list:&#10;&gt; &gt; &gt;   myOp1(&quot;name&quot;, &amp;Class::Foo, this)&#10;&gt; &gt; &gt; &#10;&gt; &gt; &gt; // constructor body:&#10;&gt; &gt; &gt;   provides()-&gt;addOperation(myOp1).doc(&quot;The foo operation&quot;);&#10;&gt; &gt; &gt; &#10;&gt; &gt; &gt;
> >
> > Thanks for pointing this one out!
> >
> > This however does not solve the inconsistency ....
> > Would it not still make sense to this:
> >
> > Property<double> value;
> > this->properties()->addProperty( "Palue", value ).doc("Value
> > Description");
> >
> > This only involves the extra typing of Property< >.
> > I just do this request because in the last couple of days at least 3
> > people in the office have been struggling with this syntax difference:
> > the above syntax compiles (so as you claim indeed fewer compilation
> > errors).... but then you have a Property< Property<double> >, which is
> > an unknown type in the taskbrowser .. and you cannot use it
> > afterwards...
> > very confusing .......
>
> I agree that we must fix this case. I think the API you propose is fine and
> should catch most cases of 'misuse'.
Great!

> I'm now first fixing the property
> composition/decomposition bugs (when writing to a file), which must be
> fixed in 2.2.1 asap.
Even greater ;-)!
>
> > > I don't think using the old syntax is really what you miss.
> > > I think
> > > automatically generating a doc-html-page for each component (similar
> > > info as the 'ls' command of a TaskContext) would solve your
> > > 'requirements' better. Similar on how ros generates documentation for
> > > each package.
> >
> > This is indeed on my wish list :) and would be great for documentation!
> >
> > However, I still like to have an overview of my component interface just
> > by looking at the header of my component, that's why I prefer to declare
> > the Properties, Operations, Ports in my header ... (although this might
> > seem old- fashioned.)
>
> I'm not against this, it's your code :-)
Of course, but you are the goeroe.

Tinne