[Bf-taskforce25] Operator standardization

Tue Feb 3 04:09:47 CET 2009

Well, if this is a documentation issue I think we can solve it with grouping.

As for not using the english language, I have a gut feeling that's
what we'll end with..

On Mon, Feb 2, 2009 at 8:20 PM, Campbell Barton <ideasman42 at gmail.com> wrote:
>> -->  (context _OT_ subcontext) _ (operation) _ (optional operation info)
> +1, using sub-contexts like this makes sense.
>
> Shaul, Id really not want to use english language word ordering, its
> unpredictable since word order would depend on the words used for each
> operator.
> Tons suggestion means functions are usefully grouped when sorted
> alphabetically in documentation, it also gives more useful
> auto-complete.
> MESH_OT_faces_* gives a nice list of all mesh face ops.
>
> Though this is also a preference from my first language being lingo
> which tried to be user friendly by mimicking English. yuck!
>
>
> On Mon, Feb 2, 2009 at 9:35 AM, Ton Roosendaal <ton at blender.org> wrote:
>> Hi Campbell,
>>
>>> Id also like to go with more
>>> specific terms at the end of the operator name. OP_OT_add_foo rather
>>> then  OP_OT_foo_add this is how most operators are already done.
>>
>> In the 2.5 spec we've noted a convention the other way around for C
>> code functions. A lot of opeators follow this convention already too.
>> :)
>>
>> The reason is that a function beginning with 'copy' or 'add' doesn't
>> say much about the context it works in, especially when there's a
>> subcontext. It also makes it a bit easier to locate, a function like
>> wm_window_copy() looks a bit more at home in wm_window.c than the
>> wm_copy_window().
>>
>> I would therefore prefer to use as ordering:
>>
>> -->  (context _OT_ subcontext) _ (operation) _ (optional operation info)
>>
>> Then we always use the verb to separate the information in 'what it
>> works on' and what it does. This then gives straight information about
>> what the operator needs as input, and is less arbitrary to apply than a
>> rule to put the "more specific terms at the end".
>>
>> so it becomes something like
>>
>> MESH_OT_faces_delete
>> MESH_OT_faces_select_similar
>>
>> MESH_OT_add_primitive_monkey
>>    (operation info is 'primitive monkey')
>>
>> MESH_OT_edges_select_shortest_path
>>    (requires selected edges to work)
>>
>> MESH_OT_edges_select_sharp
>>
>> Operations on items like modifiers, constraints, etc also get nicer
>> grouped:
>>
>> OBJECT_OT_modifier_delete
>> OBJECT_OT_modifier_add
>>
>> OBJECT_OT_constraint_delete
>> OBJECT_OT_constraint_add
>>
>> and you can give more info like
>>
>> OBJECT_OT_modifier_add_duplicate
>> OBJECT_OT_constraint_delete_unused
>> etc.
>>
>> But maybe this is just personal preference :)
>>
>> -Ton-
>>
>> ------------------------------------------------------------------------
>> Ton Roosendaal  Blender Foundation   ton at blender.org    www.blender.org
>> Blender Institute BV  Entrepotdok 57A  1018AD Amsterdam The Netherlands
>>
>> On 2 Feb, 2009, at 2:50, Campbell Barton wrote:
>>
>>> Reply inline...
>>>
>>> On Sun, Feb 1, 2009 at 6:58 AM, Blender Institute
>>> <institute at blender.org> wrote:
>>>> Hi,
>>>>
>>>> We've got now over 250 operators defined, time for some thoughts about
>>>> what good standards are for naming, flags, and property definitions.
>>>>
>>>> Campbell did interesting test with epydoc output, see here:
>>>>
>>>> Operators
>>>> http://www.graphicall.org/ftp/ideasman42/html/bpyoperator-module.html
>>>> RNA
>>>> http://www.graphicall.org/ftp/ideasman42/html/class-tree.html
>>>>
>>>> Some issues we noted;
>>>>
>>>> - operator names should try to keep in mind the part after _OT_ should
>>>> fit as a useful api name. (not MESH_OT_mesh_delete, but
>>>> MESH_OT_delete)
>>> IMHO we should go further and define some basics for word ordering for
>>> operator names..
>>> Below are some orderings that conflict, Id also like to go with more
>>> specific terms at the end of the operator name. OP_OT_add_foo rather
>>> then  OP_OT_foo_add this is how most operators are already done.
>>>
>>>
>>> - MESH_OT_add_primitive_monkey  - (add as a prefix is used mostly).
>>> - OBJECT_OT_curve_add -> OBJECT_OT_add_curve
>>>
>>> - MESH_OT_select_invert - (select as a prefix is used mostly)
>>> - GRAPHEDIT_OT_keyframes_borderselect
>>> ->GRAPHEDIT_OT_keyframes_select_border
>>> - ED_FILE_OT_border_select -> ED_FILE_OT_select_border
>>> - MESH_OT_similar_edge_select -> MESH_OT_select_similar_edge
>>> - UV_OT_loop_select -> UV_OT_select_loop
>>>
>>> Should operators specifically say they operate on the selection. Seems
>>> default, maybe operators should only have a prefix if they DONT use
>>> the select as their context (add an _all prefix). Examples
>>> - NODE_OT_delete_selection -> NODE_OT_delete
>>> - UV_OT_unlink_selection -> UV_OT_unlink
>>>
>>> For consistency? add to scene and new datatype are a bit different.....
>>> GROUP_OT_group_create -> GROUP_OT_group_add
>>>
>>> Operators that use the mouse location, what word should be used to
>>> show this
>>> pick, click, mouseclick, cursor?
>>> Assuming "click" is preferred, and "pick" when only the mouse location
>>> is used, here are my suggestions.
>>>
>>> - ACT_OT_keyframes_clickselect -> ACT_OT_keyframes_select_cick
>>> - ANIM_OT_channels_mouseclick -> ANIM_OT_channels_click
>>> - GRAPHEDIT_OT_keyframes_clickselect  ->
>>> GRAPHEDIT_OT_keyframes_select_click
>>> - OUTLINER_OT_activate_click (good)
>>> - MESH_OT_select_linked_pick -> MESH_OT_select_linked_pick
>>> - SEQUENCER_OT_select_pick_linked -> should be
>>> SEQUENCER_OT_select_linked_pick
>>>
>>> yesterday, I looked over the props and found for percent, 1 used
>>> "percentage" others "percent", some were floats, most ints. Im not
>>> really fussed but Id like to try keep some of these variable inputs
>>> consistent.
>>> I settled on percent, float since a python script may want to run an
>>> operator like vertex to sphere with a percentage of 66.6666. and I
>>> dont see any reason to force using ints.
>>>
>>> General gripe, some devs are being slack with properties, using int's
>>> instead where enum's should go, and not giving useful hard/soft limits
>>> to properties.
>>>
>>>
>>>> - selection operators should use default boolean for 'extend' and for
>>>> 'deselect' ?
>>> agree, unless anyone can think of a third option you'd want for select
>>> extend (holding shift)
>>>
>>>> - toggle operators (editmode, vpaint) should get standard enum "set,
>>>> clear, toggle", so the op->invoke() can check for this enum, and
>>>> optionally then handle toggle.
>>> agree
>>>
>>>> - add a tooltip/doc string to operators, describing the intended
>>>> operation well?
>>> agree
>>>
>>>> - classify operators well that heavily rely on mouse input, or cannot
>>>> be redone or cannot be used for the py api.
>>> agree
>>>
>>>> - standard border-select or circle-select ops should not return 'event
>>>> type' property, but some other standard like the default booleans
>>>> 'extend' and 'deselect'. Those then can later always become configured
>>>> with modal keymaps.
>>> dont understand the problem, no comment.
>>>
>>>> - in order to make a nice UI after operator executed, the used
>>>> properties should be useful in UI too. When an operator uses internal
>>>> props it should be set as such.
>>>>
>>>> - Transform is currently the most gigantic one... how can we extract
>>>> from a transform operator the useful (used?) ones, and how to
>>>> communicate the api well?
>>> agree, each 'mode' could be its own operator, will be used heavily by
>>> macro's, so having too many arguments that are only relevant in
>>> certain cases is confusing.
>>>
>>>> So! I guess people can name more issues, let's get them listed and
>>>> work
>>>> to a proposal of some kind?
>>>>
>>>> -Ton-
>>>>
>>>> ----------------------------------------------------------------------
>>>> --
>>>> Ton Roosendaal  Blender Foundation   ton at blender.org
>>>> www.blender.org
>>>> Blender Institute BV  Entrepotdok 57A  1018AD Amsterdam The
>>>> Netherlands
>>>>
>>>> _______________________________________________
>>>> Bf-taskforce25 mailing list
>>>> Bf-taskforce25 at blender.org
>>>> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>>>>
>>>
>>>
>>>
>>> --
>>> - Campbell
>>> _______________________________________________
>>> Bf-taskforce25 mailing list
>>> Bf-taskforce25 at blender.org
>>> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>>>
>>
>> _______________________________________________
>> Bf-taskforce25 mailing list
>> Bf-taskforce25 at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>>
>
>
>
> --
> - Campbell
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>