Policy: Scripting Command Page Syntax – Talk

From Bohemia Interactive Community
Jump to navigation Jump to search

Proposal

Values and commands are written with leading lowercase

Types are written with leading uppercase.

Syntax line:

The parameters should be specified as names only, with types specified below, like this:

Syntax: a min b

Parameter 1: a: Number

Parameter 2: b: Number

In the syntax line the parameter names are plain text, command is written bold.

What to do with array parameters?

--Suma 10:36, 6 September 2007 (CEST)

Type only alternative

Currently Mikero seems to be doing a lot of work changing docs into a different syntax, like:

What I do not like about this is arguments are not named, only their type is given, which seems confusing to me. However, it is clear such syntax is more concise and leads to shorter definitions. Still, I think it is not informative enough and I am against using it. Based on my proposal, this should look something like:

  • object = nearestObject position
  • object = nearestObject [ position, classType]
  • object = nearestObject [ sourceObject, classType]

sourceObject: Object

object: Object

position: Position

classType: String

--Suma 11:02, 6 September 2007 (CEST)

Mixed alternative

Mixed alternative could be to have both name and type specified at the same place, like this:

or perhaps even using types only as links (very consise, but perhaps not that clear):

--Suma 11:43, 6 September 2007 (CEST)

In my view the major change i made was to indicate very very clearly which commands returned values by saying so as part of the formal syntax. The descriptors of what they return might be too nebulous in some cases. The return and it's type, if any, was sometimes buried underneath several lines of blurb about paramaters.

I think you are over-stating the case with 'object' to make a point that 'object' generally doesn't have enough meaning to the context of the command. I definately agree it is too nebulous for most commands when 'vehicle' 'unit' or some other highly descriptive syntax can be used.

But in the above example it's the "right" descriptor to use as it is intuitive ie, what other 'thing' would you be looking for with nearestOBJECT other than???

as far as Object : object eg, my view is that it is too noisy. The command syntax (as opposed to examples) should be (as far as possible) at-a-glance.

Object | sourceObject

definately don't like this hidden link. it infers that a sourceobject is some kind of 'type'. For me, Object | unit and Object | vehicle are very clearly subtypes. Eg units and vehicles (and persons) are generic enough while being specific enough. Specific enough == many commands that are intended to work with 'vehicles'. They dont need 'tank', or 'SomeCar' in the formal syntax.

sourceobject on the other hand is in context only to the command, and in that instance I like the current style of defining it AND as a paramater, post syntax, per specific command.

There are, two broad categories of paramaters used in command syntax, one group, a large body of the commands, work on 'persons'. It would be silly eg, to say 'soldierOne' or some such in the syntax for that group. I believe. person, unit and vehicle is 'right' for them (or something similar). I hope that, barring typos, where i did stat Unit for a command, I _also_ declared it as a subtype of Object in the parameter field. (i think doing so is a good idea (tm) )

the other group is highly specific, per command, FogIntensity is far far better to use, in the syntax and in context, than something like 'number', on an individual basis.

as far as math functions go, as formal syntax 'a command b' is somewhat meaningless, and 'number' is also pretty awful. I'd suggest radians degrees, angle etc where appropriate (with an accompanying radian = number in the parameter description)


also, i noted that the terms unit (mostly) and person got mixed around in some decriptions. Sometimes unit implied soldier and could only be a soldier, other times it implied vehicle-only. The overall effect of which was to confuse the reader what a 'unit' was. And, in some descriptions the word vehicle was used when it clearly was a person. Have tried to clean those typos out.

ook? 13:40, 6 September 2007 (CEST)

I am afraid you missed my point somehow. My point is providing argument types is often not enough for functions, and arguments should be named (quite often the name will be similar to the type, but providing types is not enough). When you do not provide names, the descriptions become meaningless, as can be now seen in "Remainder of a divided by b" in mod. (I know for mod everyone probably knows what is it intended to do, but the scripting reference needs to be well formed and formal so that as little uncertainty is left about command functionality as possible)
Moreover, I do not think you should make such a large scale changes as you did recently without a previous discussion (they went unnoticed to me mostly because you marked them as "minor", otherwise I would raise the point much earlier). To avoid starting an edit war with you, I opened this discussion instead. Once we (and other people interested) come to an agreement, only then it is a time to start adjusting all command pages accordingly
I think we could take a setFog as a good starting point, as this is example which currently conforms to my 1st proposal, and illustrates it quite well. I think using the Mixed style could perhaps be better than the current form is, like:
transitionTime:Number setFog intensity:Number
One more thing can be demonstrated on this. We should agree on what identifiers start with uppercase and what with lowercase. I would prefer only types starting with uppercase, function, variable and parameter names starting with lowercase, as seen in the setFog example I have just provided. --Suma 17:05, 6 September 2007 (CEST)
I apologize in advance for any feeling of edit warz. Not my intention. I will cease and desist editing until it's formalised to what you'd like to see. (exception: nasty mistake of mine about {Code} needs an edit in two commands).
I was so used to fixing my minor typos <grin> that clicking minor edit became a habit, sorry 'bout that.
transitionTime:Number setFog intensity:Number
This 'reads' cleanly. But I fear it will be too noisy for lengthy array paramaters. Personally, i like the existing and original method of describing the paramater(s) later. Only major change I would like to see is that return values (when valid) are part of formal syntax. Perhaps an approach where some commands require no further explanation other than 'some thing' : Number ? (fog would not be one of those). I also agree with you that while 'everyone' might know what 'abs' and 'mod' do, they still require formal syntax.
the problem with lowercase parameter tokens are they are easily confused with command tokens. position eg image eg, even 'object' are literal commands. In the examples, I believe only underscore should be used when exampling a variable. Too many examples used items like 'soldier' which could conceivably be a genuine command token like 'player' in some future engine and some examples did indeed use vehicle when they meant, _vehicle. For some commands i went hunting for the non-existent reserved word 'enable'
for this reason, perhaps a good idea (tm) is introduce this to the formal syntax as well, eg
_transitionTime setFog _intensity
That might read ugly, and there's a small problem here that _local variables wont be contextually correct for some commands because the parameters used for that command are fed only from a global source (mission.sqm eg). But i think the 'evil' and confusion of what is a position and what is a _position should be cleared up disticntly in the syntax. Eg the token 'position' just shouldn't be used.
similar to the current state of Position I would like to introduce the 'subtypes' (for want of a better word) Unit, Vehicle, Person and Target. So many commands use these 'types', and quite often, in either the description or example, they were mixed up. I'm not suggesting opening a pandora's box of god knows how many 'sub' types, but the above are extensively generic. Many commands require no further explanation other that Position or Unit or ....
and to continue with your example, i believe the paramater requires further explanation 'in seconds'. Just as many of the math commands need radians or degrees (even tho they are often stated in the description)

ook? 02:10, 7 September 2007 (CEST)

I prefer the old syntax, it was clearer to me and I absolutely dislike the fact that strings are now formated as "stringVariable", where actually 99% of all programming languages enquote strings, so if I would read an example like that I would do something like ""I'm a string"" while writing a script. :) --TeRp 18:01, 6 September 2007 (CEST)

good. This is what we're here for. For me, to achieve an at-a-glance 'idea' of what the command does, i like "aString" and {Code}. They are very type specific what the intent is. ook? 02:10, 7 September 2007 (CEST)
Retrieved from "https://community.bistudio.com/wiki?title=Talk:Policy:_Scripting_Command_Page_Syntax&oldid=37610"