vmware_guest_network add error rise and improve O(folder) description

[GuideGlyph]

SUMMARY

Raise an error when vm_obj not found and improve vmware_guest_network documentation. O(folder) does not work when O(datacenter) is set by default or incorrectly. This behavior is now documented.

ISSUE TYPE

• Docs Pull Request
• Bugfix Pull Request

COMPONENT NAME

vmware_guest_network.py

ADDITIONAL INFORMATION

The module searches for the VM using def get_vm(self).
If name is in self.params, it loops through all VMs:

            objects = self.get_managed_objects_properties(vim_type=vim.VirtualMachine, properties=['name'])
            vms = []

            for temp_vm_object in objects:
                if (
                    len(temp_vm_object.propSet) == 1
                    and unquote(temp_vm_object.propSet[0].val) == self.params["name"]
                ):
                    vms.append(temp_vm_object.obj)

When multiple VMs are found, it checks:

                for vm in vms:

                    # Check if user has provided same path as virtual machine
                    actual_vm_folder_path = self.get_vm_path(content=self.content, vm_name=vm)
                    if not actual_vm_folder_path.startswith("%s%s" % (dcpath, user_defined_dc)):
                        continue
                    if user_desired_path in actual_vm_folder_path:
                        vm_obj = vm
                        break

This code selects the first matching VM, which is not ideal, but changing this behavior is out of scope for this PR.
It checks if not actual_vm_folder_path.startswith("%s%s" % (dcpath, user_defined_dc)). Without a correct O(datacenter) value, it skips the VMs.

In my scenario, I had O(folder) specified and multiple VMs with the same name in different folders. O(datacenter) was left at its default value because it was not documented as required.

As a result, find_vm() returned None, and finally get_nics_from_vm() raised an error: AttributeError: 'NoneType' object has no attribute 'config'.

[softwarefactory-project-zuul]

Build succeeded.
https://ansible.softwarefactory-project.io/zuul/buildset/0ea310707ae2464481cb7f3198045272

✔️ ansible-tox-linters SUCCESS in 4m 57s
✔️ ansible-galaxy-importer SUCCESS in 4m 14s (non-voting)
✔️ build-ansible-collection SUCCESS in 6m 51s