Experiment with Cursor-generated docs for PowerShell scripts (Olivier's take)

[AliSoftware]

Here's my attempt at asking Cursor to generate header docs for .ps1 files, to compare with @mokagio 's attempt in #159 .

Below are the prompts I used, and the answers Cursor gave me.

Notes

• This draft PR is the result of a single prompt iteration, i.e. I accepted and commited the docs it generated as-is without either manually changing anything nor following-up asking it to tweak its code, to share here exactly the code it generated on first try.
• Before asking the prompt above, I followed the steps below just to be sure it'd take the recently-added rules into account. I am not sure if those steps were absolutely necessary in practice, but given this bug report I preferred to play it safe, so here's what I did:
  • Close the window that had a8c-ci-toolkit folder open in Cursor
  • Quit Cursor
  • Checked out commit 19454a8 (i.e. the point after your cherry-picked Introduce basic .cursorrules for this repo #154 + Add Cursor rules for PowerShell scripts #155 on top of your mokagio/windows-10-experiments branch to include the .cursor/rules/*.mdc)
  • Restarted Cursor
  • And finally open the a8c-ci-toolkit-buildkite-plugin folder again in Cursor
• Notice how it took into account the powershell_scripts rule automatically—without me having to mention something like using the @rules explicitly to add them in the context—as it detected I asked it to work on files with .ps1 extension.
• Notice that after having generated the docs for the 3 *.ps1 files, it incorrectly suggested there could be more .ps1 scripts in @bin/ to update the documentation of, and listed some of our bash scripts—but hallucinating an added .ps1 extension to them. I course-corrected it by asking as a follow-up if it could check if there were other scripts to update with the .ps1 extension specifically and it realized there were none after all and stopped its hallucination right away.

[dangermattic]

	1 Warning
⚠️	Please add an entry in the CHANGELOG.md file to describe the changes made by this PR

	1 Message
📖	This PR is still a Draft: some checks will be skipped.

Generated by 🚫 Danger

[AliSoftware]

Arguably those examples are not worth including in the doc. But to be fair, the .mdc rule does include a mention of "Documentation must include […] examples", so maybe we want to tweak that part of the .mdc rule to remove the "example" part of that bullet point (and only keep the "For complex logic, provide detailed examples of different use cases" bullet point to only tell it to generate examples if the logic is complex… which is also a bullet point in the rules we could refine the wording of, to better define for it what we mean by "complex"…

[AliSoftware]

• The mention of "Administrator privileges: Yes", if correct, is an interesting information to have in the Notes imho. I have not double-checked if that requirement was correct though (but I assume we do indeed need admin role to be able to install the SDK, so it seems plausible?)
• The Disk space one is interesting… didn't expect it to document that, but in retrospect I think that's useful.
• The rest of the info in those notes is probably useless.
  • The "Author" line is probably useless for our use case and context; we should add a rules telling it not to bother adding that line.
  • The mention of internet connection being needed is not technically wrong… but not worth documenting for our case either imho. We should thus add in the rules an instruction telling that this is something we can assume is already available in all the agents/machines that will run those scripts, and that it's not necessary to document.
  • As for the Windows Requirements (Windows Server 2019 + PowerShell 5.1)… To be fair, the rules did explicitly say to document Windows specific requirements, so that's probably why it did add those additional info. We should probably remove that bullet point from the rules file.

[AliSoftware]

We probably want to remove that rule after all, given how verbose it can be in the generated doc while the info about Windows and PowerShell versions will likely not be super useful in the context we're using those scripts.

[AliSoftware]

Suggested change

	- Documentation must include: synopsis, description, parameters, examples
	- For complex logic, provide detailed examples of different use cases
	- Documentation must include: synopsis, description, parameters
	- For scripts that have a high complexity of possible parameters/arguments combinations, especially if some of them are only making sense when combined with others, or when the behavior of the script depending on the various parameters/arguments combinations could be hard to grasp, provide detailed examples of different use cases

[AliSoftware]

Suggested change

	Author: [Author name]
	Last Edit: [Date]
	Version 1.0 - Initial release
	Requirements: Windows PowerShell 5.1
	Windows Requirements:
	- Windows Server 2019 or later
	- Required Windows Features: [list features]
	- Required Windows Roles: [list roles]
	- Administrator privileges: [Yes/No]
	Requirements:
	- Required Windows Features: [list features]
	- Required Windows Roles: [list roles]
	- Administrator privileges: [Yes/No]

[AliSoftware]

Suggested change

	- Clearly document Windows version requirements or limitations
	- Document required Windows features or roles
	- Clearly document potential limitations
	- Document third-party tools the script depends on that are required to be installed explicitly first
	- Document required Windows features or roles
	- You can assume the agents will have access to internet; you don't need to document that as a requirement.