Propsal: Add `for-use-with` as a field to constants and functions

[WolfGangS]

I think it would be useful to include information for what things are meant to be used with in the generated files.

Some sort of for-use-with parameter

for example

constants:
  REZ_FLAGS:
    tooltip: Rez flags to set on the newly rezzed object. [integer flags]
    type: integer
    value: '1'
    for-use-with:
      - llRezObjectWithParams
  REZ_FLAG_TEMP:
    tooltip: Flag the object as temp on rez.
    type: integer
    value: '0x0001'
    for-use-with:
      - REZ_FLAGS

Or for Detected functions

functions:
  llDetectedDamage:
    arguments:
    - Number:
        index-semantics: true
        tooltip: ''
        type: integer
    energy: 10.0
    func-id: 554
    return: list
    sleep: 0.0
    tooltip: Returns a list containing the current damage for the event, the damage
      type and the original damage delivered.
    for-use-with:
      - on_damage
      - final_damage

Maybe broken out into multiple parameters or subsections

for-use-with-function:
  - ...
for-use-with-constant:
  - ...
for-use-with-event:
  - ...

Or

for-use-with:
  constants:
    - ...
  functions:
    - ...
  events:
    - ...

I'd be happy to try contributing this information if it's desirable.

---

This repo is using Opire - what does it mean? 👇

💵 Everyone can add rewards for this issue commenting /reward 100 (replace 100 with the amount).
🕵️‍♂️ If someone starts working on this issue to earn the rewards, they can comment /try to let everyone know!
🙌 And when they open the PR, they can comment /claim #23 either in the PR description or in a PR's comment.

🪙 Also, everyone can tip any user commenting /tip 20 @WolfGangS (replace 20 with the amount, and @WolfGangS with the user to tip).

📖 If you want to learn more, check out our documentation.

[HaroldCindy]

We're going to be doing a conversion of a lot of "prefixed" constants to also have enum / flags versions, and tag when functions expect a particular set of flags or an enum. That'll leave the existing constants in place, but guide people to using the enums.

Not too sure about the other for-use-with cases, you're discouraged from using ll.Detected* in SLua, and it'd be difficult to use that metadata to detect misuse of ll.Detected*() since the calls may happen within nested functions.

[buildersbrewery]

I had something similar for Sublime Text:

I was using:

• links to function docs on slwiki page
• links to event docs on slwiki page
• links to constant docs on slwiki page
• links to (general or other) slwiki page
• links to slwiki category page
• links to wikipedia

Compare as example:

llSay:
  description: Says the text of msg on channel
  function-id: 23
  params:
    - description: Any valid integer value
      name: channel
      type: integer
    - description: Message to be transmitted with max of 1024 bytes.
      name: msg
      type: string
  related:
    constants:
      - DEBUG_CHANNEL
      - PUBLIC_CHANNEL
    events:
      - listen
    functions:
      - llListen
      - llOwnerSay
      - llRegionSay
      - llRegionSayTo
      - llWhisper
      - llShout
      - llInstantMessage
    slwiki:
      - Hello_Avatar
      - Chat_channel
      - LSL_Protocol#Known_negative_chat_channels
    slwiki_categories:
      - LSL_Chat
  scope: support.function.builtin
  usage:
    - |-
      llSay(PUBLIC_CHANNEL, "Hello, Avatar!");