docs(iam): Update comments and terminology in IAM samples

[melaniedejong]

Description

Includes changing "member" to "principal" and linking to principal identifiers page instead of specifying recommended format.

I left "member" when it referred to the field in the role binding, since that field is still called "members."

Please merge this PR for me once it is approved

[code-review-assist]

Hi @melaniedejong and reviewers,

I'm currently reviewing this pull request and will post my detailed review in a few minutes. In the meantime, here's a quick summary to help everyone get up to speed:

This pull request updates the comments and terminology in several IAM samples within the python-docs-samples repository. The main goal is to improve clarity and consistency by replacing the term "member" with "principal" where appropriate and providing a link to the principal identifiers documentation instead of listing specific formats.

Here's a breakdown of the changes:

• Intent: Modernize terminology and improve documentation clarity regarding IAM principals.
• Changes:
  • The term "member" has been replaced with "principal" in several files to reflect best practices and Google Cloud's preferred terminology. This change is consistent throughout the code comments and docstrings.
  • Instead of explicitly listing possible formats for principal identifiers, the code now includes a link to the official Google Cloud documentation on principal identifiers. This ensures that the information remains up-to-date and avoids potential inconsistencies.
  • Affected files:
    • iam/cloud-client/snippets/iam_modify_policy_add_role.py (line 17): Changed parameter member to principal.
    • iam/cloud-client/snippets/modify_policy_add_member.py (lines 22-39): Updated docstring to use "principal" and added a link to principal identifiers documentation.
    • iam/cloud-client/snippets/modify_policy_remove_member.py (lines 22-39): Updated docstring to use "principal" and added a link to principal identifiers documentation.
    • iam/cloud-client/snippets/quickstart.py (lines 19-46 and 115-121): Updated docstrings and comments to use "principal" and added a link to principal identifiers documentation.

The changes are well-documented and easy to understand. The use of "principal" instead of "member" is a good improvement for clarity and consistency.

---

And now, a little haiku to lighten the mood:

Code flows like a stream,
Clarity's the guiding star bright,
Reviews make it shine.

[code-review-assist]

This pull request updates terminology and links in the IAM samples, replacing "member" with "principal" and providing a link to principal identifiers. The changes are well-targeted and improve the clarity of the documentation. I have a few minor suggestions based on the Google Python Style Guide to further enhance the documentation and code style.

Based on the Google Python Style Guide, I'd recommend the following general improvements:

• Docstrings: Ensure all public functions and methods have clear, concise docstrings explaining their purpose, arguments, and return values. Use triple quotes for docstrings, even if they are single-line.
• Line Length: Keep lines under 80 characters to improve readability.
• Blank Lines: Use two blank lines between top-level functions and classes, and one blank line between methods within a class.
• Naming: Use descriptive names for variables and functions. For constants, use all uppercase letters with underscores separating words (e.g., MAX_VALUE).

[code-review-assist]

Per the Google Python Style Guide, there should be two blank lines between top-level functions. Consider adding an extra blank line here.

Suggested change

	def modify_policy_add_role(policy: dict, role: str, principal: str) -> dict:
	def modify_policy_add_role(policy: dict, role: str, principal: str) -> dict:

[code-review-assist]

Consider renaming the member parameter to principal for consistency with the updated terminology.

Suggested change

	project_id: str, role: str, member: str
	project_id: str, role: str, principal: str

[code-review-assist]

Consider renaming the member parameter to principal for consistency with the updated terminology.

Suggested change

	project_id: str, role: str, member: str
	project_id: str, role: str, principal: str

[code-review-assist]

Consider adding a more descriptive docstring, summarizing the steps involved in the quickstart and the purpose of each parameter. For example:

"""Demonstrates basic IAM operations.

This quickstart shows how to get a project's IAM policy, add a principal to a role, list members of a role, and remove a principal from a role.

Args:
    project_id: The ID or number of the Google Cloud project.
    member: The principal ID.
"""

Suggested change

	def quickstart(project_id: str, member: str) -> None:
	def quickstart(project_id: str, member: str) -> None:
	"""Demonstrates basic IAM operations.
	This quickstart shows how to get a project's IAM policy, add a principal to a role, list members of a role, and remove a principal from a role.
	Args:
	project_id: The ID or number of the Google Cloud project.
	member: The principal ID.
	"""

[code-review-assist]

According to the Google Python Style Guide, prefer using f-strings for formatting. Change print("Members: ") to print(f"Members: ").

[code-review-assist]

Update the placeholder comment to reflect the change from "member" to "principal". Per Google Python Style Guide, use a complete sentence in your comment.

Suggested change

	# TODO: Replace with the ID of your principal.
	# For examples, see https://cloud.google.com/iam/docs/principal-identifiers
	# TODO: Replace with the ID of your principal.

[code-review-assist]

Update the variable name to principal for consistency.