Rename: Std_ClippingPlane to Std_ToggleClipPlane

Discussions about the wiki documentation of FreeCAD and its translation.
vocx
Posts: 3283
Joined: Thu Oct 18, 2018 9:18 pm

Re: Rename: Std_ClippingPlane to Std_ToggleClipPlane

Postby vocx » Thu Jan 23, 2020 4:09 pm

DeepSOIC wrote:
Thu Jan 23, 2020 12:15 am
is everyone just going to not notice the "toggle" word in the command strings being utterly wrong :roll: ? The command opens a task where you can toggle some clipping planes, but in itself does not toggle anything...
Of course, however, that would mean changing the name of the C++ classes and command name. This could be done at another time. Right now we want to match the code to the wiki. This renaming is done so that the Std_WhatsThis system works correctly when launching the documentation system of FreeCAD.

My personal belief is that a command name should be an "object" (noun) as opposed to an "action" (verb).

So, it should be name Std_ClippingPlane, and not Std_ToggleClippingPlane; it should be Std_Primitives and not Std_CreatePrimitives, etc. This is better when talking about the result of those commands and when writing documentation.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.
User avatar
DeepSOIC
Posts: 7476
Joined: Fri Aug 29, 2014 12:45 am
Location: Saint-Petersburg, Russia

Re: Rename: Std_ClippingPlane to Std_ToggleClipPlane

Postby DeepSOIC » Thu Jan 23, 2020 4:34 pm

vocx wrote:
Thu Jan 23, 2020 4:09 pm
My personal belief is that a command name should be an "object" (noun) as opposed to an "action" (verb).
My opinion is exact opposite: a command IS an action, i.e. it sorta IS a verb, and should be named accordingly: with a verb in it. I don't mind the current situation too much, though, where many commands are named after the objects they create, and thus the objects and the commands share their wiki pages.
vocx
Posts: 3283
Joined: Thu Oct 18, 2018 9:18 pm

Re: Rename: Std_ClippingPlane to Std_ToggleClipPlane

Postby vocx » Fri Jan 24, 2020 1:59 am

DeepSOIC wrote:
Thu Jan 23, 2020 4:34 pm
...many commands are named after the objects they create, and thus the objects and the commands share their wiki pages.
But then how would you document it? "The Std_CreatePlane command creates a Plane. See the documentation of Plane."

The action would have barely any documentation; it would just point to the object. So, I think it makes more sense to document objects.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.