[Bf-taskforce25] Operator standardization

Tue Feb 3 04:48:08 CET 2009

This would mean adding  sub-grouping to operators, the RNA grouping
stuff doesn't apply here.
It still wouldn't be as nice for auto-completion .

I meant not using English grammar - or "word ordering" as us
uneducated people say :)

On Mon, Feb 2, 2009 at 7:09 PM, Shaul Kedem <shaul.kedem at gmail.com> wrote:
> 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
>>
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>

-- 
- Campbell