Format and add comments to creatpw.ps1 function

Hermes/Funktionen/creatpw.ps1

@@ -1,3 +1,32 @@
+<#
+.SYNOPSIS
+    Erstellt ein Passwort für einen Active Directory-Benutzer basierend auf Vor- und Nachname.
+
+.DESCRIPTION
+    Die Funktion generiert ein zufälliges Passwort im Format "##*<Code>*##".
+    Der Code besteht aus:
+    - Erster Buchstabe des Vornamens (groß) + letzter Buchstabe des Vornamens (klein)
+    - Erster Buchstabe des Nachnamens (groß) + letzter Buchstabe des Nachnamens (klein)
+    - Länge des Vornamens (maximal 9)
+    - Länge des Nachnamens (maximal 9)
+    Umlaute und Sonderzeichen werden ersetzt.
+
+.PARAMETER Vorname
+    Der Vorname des Benutzers
+
+.PARAMETER Nachname
+    Der Nachname des Benutzers
+
+.PARAMETER user
+    Der SamAccountName des Active Directory-Benutzers
+
+.PARAMETER ChangePasswordAtLogon
+    Gibt an, ob das Passwort bei der nächsten Anmeldung geändert werden muss ($true/$false)
+
+.EXAMPLE
+    creatpw -Vorname "Müller" -Nachname "Becker" -user "mbecker" -ChangePasswordAtLogon $true
+#>
+
 function creatpw {
     param(
         [string]$Vorname,
@@ -6,34 +35,40 @@ function creatpw {
         [bool]$ChangePasswordAtLogon
     )
 
-  # Umlaute ersetzen
+    # Umlaute und Sonderzeichen ersetzen
     $Vorname = $Vorname.Replace('ö', 'oe').Replace('ä', 'ae').Replace('ü', 'ue').Replace('ß', 'ss').Replace('Ö', 'Oe').Replace('Ü', 'Ue').Replace('Ä', 'Ae')
     $Nachname = $Nachname.Replace('ö', 'oe').Replace('ä', 'ae').Replace('ü', 'ue').Replace('ß', 'ss').Replace('Ö', 'Oe').Replace('Ü', 'Ue').Replace('Ä', 'Ae')
 
-  # Groß-/Kleinschreibung
+    # Namen in Großbuchstaben konvertieren
     $Vorname = $Vorname.ToUpper()
     $Nachname = $Nachname.ToUpper()
+
+    # Kleinbuchstaben-Versionen für Codegenerierung
     $VornameK = $Vorname.ToLower()
     $NachnameK = $Nachname.ToLower()
 
-  # Code-Zeichen
+    # Code generieren: erster Buchstabe groß, letzter Buchstabe klein
     $CodeVorname = $Vorname[0] + $VornameK[-1]
     $CodeNachname = $Nachname[0] + $NachnameK[-1]
 
-  # Länge begrenzen
+    # Namenslänge bestimmen und auf maximal 9 Zeichen begrenzen
     $Vornameanzahl = $Vorname.Length
     $Nachnameanzahl = $Nachname.Length
+
     if ($Vornameanzahl -ge 9) { $Vornameanzahl = 9 }
     if ($Nachnameanzahl -ge 9) { $Nachnameanzahl = 9 }
 
-  # Passwort zusammenstellen
+    # Finale Passwort-Zusammensetzung
     $Codename = "##*" + $CodeVorname + $CodeNachname + $Vornameanzahl + $Nachnameanzahl + "*##"
 
-  # Passwort setzen und Account aktivieren
+    # Passwort im Active Directory setzen und Benutzer aktivieren
     Set-ADAccountPassword -Identity $user -NewPassword (ConvertTo-SecureString -AsPlainText $Codename -Force) -Reset
     Enable-ADAccount -Identity $user
+
+    # Festlegen, ob das Passwort bei der nächsten Anmeldung geändert werden muss
     Set-ADUser -Identity $user -ChangePasswordAtLogon:$ChangePasswordAtLogon
 
+    # Ausgabe des generierten Passworts und Kopieren in die Zwischenablage
     Write-Host "$user - $Vorname - $Nachname : $Codename ( Kennwort ist im Zwischenspeicher. )"
     Set-Clipboard $Codename
 }