What is the nature and description of the request?

The lookup plugins included with the vmware_rest collection are not intuitive and too lightly documented to be consumed easily. Someone attempting to use it would likely have the following questions that would slow or block their ability to use the plugin and perhaps the entire collection.

1. Include a link to what a lookup plugin is used for

1. This may seem basic but having a quick description and/or a link to the lookup plugin docs would be helpful
2. https://docs.ansible.com/ansible/latest/plugins/lookup.html#lookup-plugins

2. Include why filter plugins are being used in this collection

1. The why is really important here because as a new user of the collection it doesn't make sense why I need to add a bunch of code to a lookup plugin when I'm already using a module specific to this purpose

3. Provide a working example comparing the lookup plugin vs using the specific module + set_fact

1. The plugin shows some examples of /my_dc/host/my_cluster but that path doesn't mean anything to someone not familiar with how vmware handles its internal data structures
2. Showing a code comparison for the code below with the lookup plugin would make it obvious why the plugin is preferred and how the plugin parameters should be structured (code below)

- name: List datacenters
  vmware.vmware_rest.vcenter_datacenter_info: 
    filter_names: 
      - "my_datacenter_name"
  register: _datacenter_info

- name: Debug datacenter info
  ansible.builtin.debug: 
    var: _datacenter_info

- name: Set Datacenter fact
  ansible.builtin.set_fact: 
    datacenter_moid: "{{ _datacenter_info.value[0].datacenter }}"

vs

- name: lookup MoID of the object
  ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_datacenter_name', **connection_args) }}"

4. Include a better description in the plugin specific readme for _terms

1. The current description only says "Path to query." This doesn't mean anything to someone unfamiliar to using the lookup plugin and/or vmware's internal data structure.

5. Explain how or link to something that explains how to get the data required for the 'Path to query'

1. Looking at the example /my_dc/host/my_cluster someone might be able to assume that my_dc should be replaced with something relating to your datacenter. If they do make that assumption it still doesn't tell them if its the name or MOID.
2. If the name has a space or special character in it, how does the filter plugin handle it? Do they need to modify the value for it to be interpreted correctly?

6. Provide a more relevant example

1. ansible.builtin.debug for the variable isn't a usecase that anyone would specifically need this plugin for. This example should be more geared towards a use case that people will use it with such as creating an object and setting a fact.

7. The hint at the bottom of the plugin modules doesn't make sense on its own and needs more context.

1. "Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up."

8. Consider including lookup code as part of the modules

1. The current design of having each module unable to lookup the data it needs to function and depending on properly formatted lookup functions shifts far too much complexity onto the playbooks.
2. The use of the lookup plugins rather than module functionality makes the plays difficult to read and write
3. The difficulty in reading and writing the playbooks makes it less likely to be used by users who may be considering moving away from the community vmware collection
4. The level of complexity in the playbooks makes it more difficult to test and maintain playbooks / roles

Why does the customer need this? (List the business requirements here)

The lookup plugins seem to be essential to using this vmware_rest collection if you don't want to have to jump through hoops to get the data using stand alone modules with set_fact. However they aren't documented well enough to prevent many if not most users from just pivoting back to using the community vmware collection rather than trying to figure it out on their own.

How would you like to achieve this? (List the functional requirements here)

1. Improve the documentation with recommendations above.
2. Create modules using the REST API that include the lookup plugin functionality so that the lookup plugin isn't necessary at all

Github Link if any

Example where I went through the whole process of building a role to create a vm without using the lookup plugins because I couldn't make sense of how to use them properly.
https://github.com/jeffcpullen/create_vsphere_vm/tree/1.0.0