Implement logic if commitPolicyTimeout is Set, commitPolicy is Mandatory.

[wcarroll]

https://github.com/ZertoPublic/ZertoApiWrapper/blob/73540faeb90e1461f3e4d489b1e415f2bbf890f0/ZertoApiWrapper/Public/Invoke-ZertoMove.ps1#L24-L24

[gdbarron]

Hey @wcarroll. I'm working on this and a few other updates to Invoke-ZertoMove, but I wasn't sure how the external help got updated. Is that done via an automated process?

If you don't mind, I'd be curious on your feedback before I submit the PR in case you really dislike the changes 😄 . I've introduced new parameter sets and removed some as well. I moved much of setting the body params to the begin block as they don't change in the process block. I added a new parameter for vpgIdentifier and made it accessible via pipeline input so folks can pipe objects from Get-ZertoVpg and initiate multiple moves.

I'm not sure if there's a way around the multiple HelpMessage entries as it's not the cleanest.

https://github.com/gdbarron/ZertoApiWrapper/commit/0630cbb20e0c9ccb512a26f01575b02c7dec2065

[wcarroll]

This is fantastic.

To answer your question, I use PlatyPS for automating the majority of the documentation. If you run the build.ps1 script it will install all the required modules and run through the build process that should take about a minute. This will download several modules to run my automated build process. After this has been run once you can start using the Invoke-Build updatemarkdownhelp command (doing this from memory on my phone, I'll be able to check the code later if this command doesn't work). This will build the module and then update the help files. I should warn you that this may make minor changes to more files than you intend. I am working on fixing this, but in the meantime, discard all changes except for the help file you are working to update. From there you can validate and edit the markdown help file in the docs folder with and additional examples, descriptions, etc.

Thanks for taking a look at this and love the cleanup. I this this was one of the earliest functions I wrote and does need the refactoring.

Thanks!

[gdbarron]

Cool, glad you like the approach. I'll try and walkthrough the steps. Out of curiosity, why did you go with this approach for commenting as opposed to inline help?

[wcarroll]

External vs. comment based help was decision that I struggled with, but a decision that I had to make early on. I ended up deciding on the external approach to streamline the external documentation by leveraging the markdown files here on GitHub as an easy way to allow for online help as well as a method to quickly update the help files without having to understand powershell at all.

Looking back, it is a decision I'm not 100% happy with but going back to update each and every function is beyond daunting. If I ever need to do this again, I will evaluate comment based help again and see if the comment based help makes more sense then.

Would like to know your thoughts.

[gdbarron]

Your steps worked and I've initiated the PR. Hopefully it looks good; let me know if there's anything else to be done.

As for the help, I've only ever used comment based help and extracted out with PlatyPS when I wanted to do something else with it. You make a good point about not having to understand powershell at all, but I guess it's either you need to know PS comment based help or you need to know markdown. Perhaps markdown is more universal and that makes your approach better. Then again, other than perhaps very large corporations who have dedicated folks for documentation, PS devs are typically doing their own 😄 Not sure there's a 'right' answer, but I'll definitely give it some more thought.

[wcarroll]

@gdbarron Thanks for knocking this out. I am working on a couple of additional functions for VPG creation to Azure. Once I have those knocked out, I'll get this update published to the gallery. Have a great weekend.

Thanks, Wes