Policy: Scripting Command Page Syntax – Talk

From Bohemia Interactive Community
Revision as of 17:01, 6 September 2007 by TeRp (talk | contribs)
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 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)

Retrieved from "https://community.bistudio.com/wiki?title=Talk:Policy:_Scripting_Command_Page_Syntax&oldid=37604"