docs: Specify how the recursive argument to directory() works

[cliffmccarthy]

• As described in issue files.directory doesn't ensure recursive ownership (add op arg) #1435, the 'recursive' argument to files.directory() does not ensure recursive ownership of the entire directory tree. Only ownership of the top-level directory is checked, not that of the subdirectories and files. Specifying 'recursive=True' will have no effect if the top-level directory already matches the mode, user, and group.
• This is how the operation has behaved for a long time, so changing existing functionality to check the entire tree could be undesirable. It also takes more time to check the entire tree, so doing so affects performance. A new option may be provided in the future for callers to explicitly check the whole tree when this is desired.
• Documented the existing behaviour of 'recursive' in the files.directory() docstring.

• Pull request is based on the default branch (3.x at this time)
• Pull request includes tests for any new/updated operations/facts
• Pull request includes documentation for any new/updated operations/facts
• Tests pass (see scripts/dev-test.sh)
• Type checking & code style passes (see scripts/dev-lint.sh)

[cliffmccarthy]

The lint failures are in an unrelated file. At the time of the 3.5 tag, which is the current top-of-branch, the workflow passed; the failures are the result of an unpinned mypy version. At the time of 3.5, mypy was version 1.17.1; version 1.18.1 of mypy was released yesterday and introduces this failure.

[Fizzadar]

Thanks for documenting this, @cliffmccarthy!

Augh mypy, I’m going to pin it since I’m fed up of it breaking CI 🙃

[cliffmccarthy]

You're welcome! Once top-of-branch is updated and passing, I'll rebase this so we can get a clean run.

[Fizzadar]

Rebased to fix mypy + update file location (after b14c575 merged).