yade-dev team mailing list archive

[Bruno Chareyre <bruno.chareyre@xxxxxxxxxxxxxxx>]

On 22/07/15 17:52, Jerome Duriez wrote:
> Hi,
>
> I modified the documentation of "engines" attribute of "Omega" class.
> The logic behind is that maybe some users do not know that Omega
> object is accessed through "O"...
> (at least this does not appear on
> https://yade-dem.org/doc/yade.wrapper.html#omega)
>
> Then why precising it only for "engines", and not other attributes ?
> Because there was this "Scene::engines" I considered as probably
> meaningless on its own for many users.
>
The "Scene::engines" part is a note for programmers, not a problem if
meaningless for users, they don't need it.
The key part of my remark is that, normally, a user will never find the
documentation of O.engines if he doesn't know "O" in the first place. So
it is pointless.
"O" is seldom found in every parts of the documentation
(https://yade-dem.org/doc/user.html#scene-construction).

The reason why it does not appear in the documentation of Omega is that
it really does not have to.
The fact that you can write
 HAHA=array(10)
 HAHA.argmin()
 Out[7]: 0
does not imply that the documentation of numpy arrays should refer to
HAHA (and obviouly numpy devs couldn't guess that someone would
instanciate an array object with this name).

It is exactly the same here. You put in class doc how the objects of
this class should be named.
So now I can do this:
 bla=Omega()
 bla.engines?
 Docstring:  [...] accessed using O.engines

Do you see the problem? Do I really access the engines of "bla" as
"O.engines"? Just weird.
It is not only useless, it is also inconsistent. So yes, I think it is
better to revert.

Bruno



> If you think it hurts, you may revert..
>
> Jerome
>
> ------------------------------------------------------------------------
> *From:* Yade-dev
> [yade-dev-bounces+jerome.duriez=ucalgary.ca@xxxxxxxxxxxxxxxxxxx] on
> behalf of Bruno Chareyre [bruno.chareyre@xxxxxxxxxxxxxxx]
> *Sent:* July 22, 2015 3:59 AM
> *To:* yade-dev@xxxxxxxxxxxxxxxxxxx
> *Subject:* Re: [Yade-dev] [Branch ~yade-pkg/yade/git-trunk] Rev 3705:
> Addition in doc of Omega.engines to state it is = to O.engines in python
>
> Hi Jérôme,
> I'm unsure about the logic of this.
> The documentation of O.engines now tells that it can be accessed as
> O.engines.
> Along this line the documentation should also tell that O.resetTime()
> can be accessed via O.resetTime(), and the same reasoning applies to
> all attributes (O.interactions, O.forces, etc.).
> B
>
> On 21/07/15 23:10, noreply@xxxxxxxxxxxxx wrote:
>> ------------------------------------------------------------
>> revno: 3705
>> committer: jduriez <jerome.duriez@xxxxxxxxxxx>
>> timestamp: Tue 2015-07-21 10:54:29 -0600
>> message:
>>   Addition in doc of Omega.engines to state it is = to O.engines in python
>> modified:
>>   py/wrapper/yadeWrapper.cpp
>>
>>
>> --
>> lp:yade
>> https://code.launchpad.net/~yade-pkg/yade/git-trunk
>>
>> Your team Yade developers is subscribed to branch lp:yade.
>> To unsubscribe from this branch go to https://code.launchpad.net/~yade-pkg/yade/git-trunk/+edit-subscription
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~yade-dev
>> Post to     : yade-dev@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~yade-dev
>> More help   : https://help.launchpad.net/ListHelp
>
>
> -- 
> _______________
> Bruno Chareyre
> Associate Professor
> ENSE³ - Grenoble INP
> Lab. 3SR
> BP 53
> 38041 Grenoble cedex 9
> Tél : +33 4 56 52 86 21
> Fax : +33 4 76 82 70 43
> ________________
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~yade-dev
> Post to     : yade-dev@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~yade-dev
> More help   : https://help.launchpad.net/ListHelp


-- 
_______________
Bruno Chareyre
Associate Professor
ENSE³ - Grenoble INP
Lab. 3SR
BP 53
38041 Grenoble cedex 9
Tél : +33 4 56 52 86 21
Fax : +33 4 76 82 70 43
________________