FindPkgConfig: Update documentation

- Synced module documentation with other find modules.
- Added intro code block showing how to use this module.
- Added separate examples section with more examples.
- Moved all documentation to the top header comment to make it easier
  to manage and adjust.
- Documented commands arguments as a list.
- Removed internal comment defining "Local variables" for some editors
  (other files don't have these defined).
- Changed variable references definitions to a normal list, as these
  don't seem to be needed to be referenced in other documentation files
  and to be more synced with other find modules. In case some special
  environment variable, should be referenced, it can be added in the
  future to the variables section directly and to be foundable on the
  variables index list.
- Briefly described also PKG_CONFIG_PATH and PKG_CONFIG environment
  variables, as they are already mentioned in the descriptions.
- Added "See Also" section.