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'
I think confusion with command tokens is avoided by using bold names for commands. However, using leading underscores for parameter names could be reasonable as an additional measure to make it clear. --Suma 10:39, 7 September 2007 (CEST)
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 ....
I think the idea of subtypes not exactly correct here. The commands really accepts any Object, and passing any Object is syntactically correct, which is what we are for when describing syntax. The fact the function does nothing for some subtypes should be described in description, and it can be moreover indicated by using appropriate parameter name, like vehicle:Object. --Suma 10:39, 7 September 2007 (CEST)
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 guess we will agree soon here. My clarification would be seconds and radians/degrees are actually a 3rd think: we have parameter name, which would be angle, then parameter type, which would be Number, and then parameter units, which would be degrees or radians (or seconds). It could be well indicated by using appropriate parameter name, like return:Number = angleInDegress:Number sin --Suma 10:39, 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)
I agree here. When I write String or Code, one can provide any compatible expression, which can be a literal (i.e "Some string" or {Some_Code}, but also a non-literal computed value, like format [foo], or compile "another_foo". I do not think using literals in syntax description makes it clear enough, types should be described in some formal way. --Suma 10:39, 7 September 2007 (CEST)

summary?

I think bold has been the cleanest and most sensible approach to distinguish command from paramaters, and I believe I have cleaned out the pages where things other than command were in bold. I noticed on some pages italic was used for paramaters but they tend to look ugly and I dont think are necessary.

I still remain wary of nasty parameter tokens like 'position'. But as I recall it was more to do with the examples than confusion in command syntax (and bold should sort that out).

in summary i'd like to see

  • the return value (when valid) declared as part of the formal syntax
  • underscores mandatory for any examples where a _variable is used

A pity, because they sure as hell look good. <grin>

  • harping on units

I don't know best way. 'Unit', 'vehicle' and 'person' have been interchanged, willy nilly in quite a few descriptions and etc, where they either weren't appropriate or changed meaning between different command syntaxes. Sometimes a vehicle was described, when either a vehicle or a person was appropriate (eg a unit). Sometimes a 'unit', when a 'vehicle' was only pssibility, etc.

When i'm looking thru the commands, to see unit (meaning command will operate 'correctly' on either vehicles or persons), it helps me, greatly. Similarly the generic 'object' is very helpful to know the command works on any object, including vehicles eg. An 'object' in this sense specifically means all Object types are appropriate . Wheras (for me) a 'target' or 'person' is not an 'object'.

Of course, all of these are Objects, but that is from the perspective of the engine, not, the person trying to understand how to use the command.

This is not about "engine", this is about language syntax. There are no distinct types for Tank, Vehicle, ... in the scripting language, therefore such types should not be used when describing argument type in the syntax. --Suma 18:36, 8 September 2007 (CEST)

I'm arguing here that these names are endemic to perhaps 50% of the command syntax and should be formalised in some way (or this policy page make very clear when to use the terms,and especially when NOT to use the terms!) I note for instance that 'target' (also quite heavily used) may become has become? a genuine Type in it's own right? It would be 'nice' if we could more formalise these oft used token nanes. ook? 02:47, 8 September 2007 (CEST)

Yes, Target is a specific type. It is however a distinct type, and it is not interchangeable with Object. --Suma 18:36, 8 September 2007 (CEST)
Position is not a type either, and yet it is extensively used to define a paramater. I'm recommending that Unit, Person, Vehicle, (and formerly Target when it wasn't a true type) be treated in the same manner. Mikero (nee Ook?) 23:47, 8 September 2007 (CEST)

Optional Parameters Proposal

In the syntax field for commands, I think it would be convenient for readers if when we listed optional parameters, they are italicized and enclosed in (parenthesis). I've seen this done on a few pages and personally I found this to be extremely helpful. Thoughts? -DreadedEntity (talk) 02:33, 21 June 2015 (CEST)

Optional params usualy have (Optional) next to them, which imo pretty explicit already. Not sure if making them italic will make it so much better that it would justify the enormous amount of work needed for this to happen. Killzone_Kid (talk) 11:01, 21 June 2015 (CEST)
@DreadedEntity I usually do this when I notice it. I also try to italicize text in the syntax aswell like this:
param exampleCommand [requiredParam, optionalParam];
Benargee (talk) 16:38, 21 June 2015 (CEST)
Retrieved from "https://community.bistudio.com/wiki?title=Talk:Policy:_Scripting_Command_Page_Syntax&oldid=353142"