Associate LSL Functions with Enums

[tapple]

• Follow up to Classified all the LSL constants into enums #104
• Part of Proposal: Constant definitions - grouping, subtypes, arguments #31
• Closes Propsal: Add for-use-with as a field to constants and functions #23

Add new annotations to function arguments:

• enum-semantics
• param-semantics
• param-get-semantics

Add new annotations to functions:

• enum-semantics
• param-get-semantics

Add new enum types:

• param-list
• paam-dict

[HaroldCindy]

Generally looks pretty good, thanks for this! Just a couple of notes.

[HaroldCindy]

s/to/of/?

[tapple]

fixed; da8e94b

[HaroldCindy]

I'm a bit mixed on the idea of param-dict. Yes, incidentally that may be how we end up using the enum, but in terms of the actual grouping it's strictly an enum, yea? Seems like the param-dict-ness for uses of that enum is something better expressed through a ruleset or something.

[tapple]

The documentation generator will probably need to treat the 5 types of enums uniquely:

type	Documentation fields
enum	name, decimal value, description
flag	name, hex value, description
enum+flag	both of the above
param-list	name, parameter names+types, value names+types, description
param-dict	name, type, default value, description

It's hard to be sure with the parameter metadata not yet being in the file and a documentation generator for parameters not yet existing

I would prefer all the data currently in the ruleset section was in the constants and enums sections. I haven't yet made that PR, so don't yet know if there's complications doing that

I can change it back to enum until we have an actual generator, if you want

[HaroldCindy]

Hmmm, so here's my thinking:

Think about how you might specify these rulesets in something like Python. IntEnums and IntFlags would naturally be separate from definitions about what they mean in a specific contexts. For example, it would be strange to specify in an enum itself that it's sometimes used as a key with a certain number of values after it.

The most obvious place this shows up is in GPP/SPP. Both use keys from the same enum, but the way they're used is totally different, one with a list-like structure and the other with a dict-like structure. In Python you might handle this by having SPP take a usage-specific TypedDict subclass and having GPP take a List[SomeEnum], but you'd end up with 1 enum and 2 distinct argument types. Does that make sense?

[tapple]

no, I'm not understanding you:

1. I don't really understand what you're trying to say regarding enums, python, and get/set primitive params. There wouldn't be such a thing as parameter lists if the api was designed for python.
2. I'm unsure if get/set prim params is the best example for what you're trying to illustrate, as it uses list semantics. Maybe get/set prim media params illustrates your point better?
3. I think this is still a reason I should change prim-list and prim-dict back to enum, but I'm not sure

I'm mentally classifying functions into 4 categories with this PR:

	param-semantics	param-get-semantics
param-list	llParcelMediaCommandList llRezObjectWithParams llSetAgentEnvironment llSetEnvironment llSetLinkPrimitiveParams llSetLinkPrimitiveParamsFast llSetPayPrice llSetPrimitiveParams	llGetEnvironment llGetLinkPrimitiveParams llGetPrimitiveParams llParcelMediaQuery
param-dict	llCastRay llCreateCharacter llEvade llFindNotecardTextCount llFindNotecardTextSync llFleeFrom llGetAgentList llGetAttachListFiltered llGetClosestNavPoint llGetStaticPath llGiveAgentInventory llHTTPRequest llLinkParticleSystem llMapBeacon llNavigateTo llParticleSystem llPatrolPoints llPursue llSetCameraParams llSetGroundTexture llSetKeyframeMotion llSetLinkGLTFOverrides llSetLinkMedia llSetParcelForSale llSetPrimMediaParams llTransferOwnership llUpdateCharacter llWanderWithin	llGetLinkMedia llGetObjectDetails llGetParcelDetails llGetPrimMediaParams

I'm thinking:

• param-semantics means parameters are being written, and is specific to the using function
• param-get-semantics means parameters are being read, and is specific to the using function
• param-dict means every param has exactly 1 value, and applies to all users of the enum (both getters and setters)
• param-list means each param has 0-8 parameters, not just one. This applies to all users of the enum (both getters and setters)

Maybe the distinction between function properties and enum properties is not very important, as only 4 enums have both a getter and setter function:

• EnvironmentParam/EnvironmentParamReadOnly
• ParcelMediaCommand/ParcelMediaQuery
• PrimMediaParam
• PrimParam/PrimParamGet

And, now that I listed them out, it looks like I separated the read and write params into seperate enums anyway, except PrimMediaParam. I separated them for an unrelated reason: getter functions can only read a subset of the fields that setter functions can set. Though, if I seperated PrimMediaParam, then get/set could also technically be an enum property.

In a previous iteration of this PR, other-values and enum+flag was also a function property, not an enum property. I moved them both to enum property since every function shared the same value

param-dict and param-list enums are definitely also enums. I mostly made them a seperate enum type because

1. they would have different handling in the documentation generator
2. They probably need different handling in the rulesets, if that ends up using this data
3. I can't think of any generator that would need to handle enum, param-dict, and param-list enums one way, and flag enums another way