update docs... still needs work

Author: santisq

docs/en-US/Get-ADEffectiveAccess.md

@@ -13,10 +13,34 @@ schema: 2.0.0
 
 ## SYNTAX
 
+### Identity (Default)
+
+```powershell
+Get-ADEffectiveAccess
+    -Identity <String>
+    [-Audit]
+    [-IncludeDeletedObjects]
+    [-Credential <PSCredential>]
+    [-Server <String>]
+    [-AuthenticationTypes <AuthenticationTypes>]
+    [<CommonParameters>]
+```
+
+### Filter
+
 ```powershell
-Get-ADEffectiveAccess [[-LdapFilter] <String>] [-Audit] [-Top <Int32>] [-IncludeDeletedObjects]
- [-SearchScope <SearchScope>] [-Credential <PSCredential>] [-Server <String>]
- [-ProgressAction <ActionPreference>] [<CommonParameters>]
+Get-ADEffectiveAccess
+    [[-LdapFilter] <String>]
+    [-Audit]
+    [-Top <Int32>]
+    [-IncludeDeletedObjects]
+    [-SearchScope <SearchScope>]
+    [-SearchBase <String>]
+    [-Credential <PSCredential>]
+    [-Server <String>]
+    [-PageSize <Int32>]
+    [-AuthenticationTypes <AuthenticationTypes>]
+    [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -27,7 +51,7 @@ Get-ADEffectiveAccess [[-LdapFilter] <String>] [-Audit] [-Top <Int32>] [-Include
 
 ### Example 1
 
-```powershell
+```
 PS C:\> {{ Add example code here }}
 ```
 
@@ -37,7 +61,7 @@ PS C:\> {{ Add example code here }}
 
 ### -Audit
 
-{{ Fill Audit Description }}
+Use this switch to include audit rules for the security descriptor from the system access control list (SACL).
 
 ```yaml
 Type: SwitchParameter
@@ -46,14 +70,16 @@ Aliases:
 
 Required: False
 Position: Named
-Default value: None
+Default value: False
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
 ### -Credential
 
-{{ Fill Credential Description }}
+Specifies a user account that has permission to perform this action. The default is the current user.
+
+Type a user name, such as `User01` or `myDomain\User01`, or enter a [`PSCredential`](https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.pscredential) object generated by the [`Get-Credential` cmdlet](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/get-credential). If you type a user name, you're prompted to enter the password.
 
 ```yaml
 Type: PSCredential
@@ -69,7 +95,9 @@ Accept wildcard characters: False
 
 ### -IncludeDeletedObjects
 
-{{ Fill IncludeDeletedObjects Description }}
+Use this switch to include deleted objects in your search. This switch is also required when getting the ACL for a deleted Identity.
+
+For more details, see [`DirectorySearcher.Tombstone` Property](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.directorysearcher.tombstone#system-directoryservices-directorysearcher-tombstone).
 
 ```yaml
 Type: SwitchParameter
@@ -78,18 +106,20 @@ Aliases:
 
 Required: False
 Position: Named
-Default value: None
+Default value: False
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
 ### -LdapFilter
 
-{{ Fill LdapFilter Description }}
+Specifies an LDAP query string that is used to filter Active Directory objects you want to get the ACL from.
+
+For more details, see the [__Remarks__ section from `DirectorySearcher.Filter`](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.directorysearcher.filter#remarks).
 
 ```yaml
 Type: String
-Parameter Sets: (All)
+Parameter Sets: Filter
 Aliases:
 
 Required: False
@@ -101,24 +131,44 @@ Accept wildcard characters: False
 
 ### -SearchScope
 
-{{ Fill SearchScope Description }}
+Specifies the scope of an Active Directory search. The acceptable values for this parameter are:
+
+- `Base` or `0` - Searches only the current path or object
+- `OneLevel` or `1` - Searches the immediate children of that path or object
+- `Subtree` or `2` - Searches the current path or object and all children of that path or object
 
 ```yaml
 Type: SearchScope
-Parameter Sets: (All)
+Parameter Sets: Filter
 Aliases:
 Accepted values: Base, OneLevel, Subtree
 
 Required: False
 Position: Named
-Default value: None
+Default value: Subtree
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
 ### -Server
 
-{{ Fill Server Description }}
+Specifies the AD DS instance to connect to by providing one of the following values for a corresponding domain name or directory server.
+
+Domain name values:
+
+- Fully qualified domain name
+- NetBIOS name
+
+Directory server values:
+
+- Fully qualified directory server name
+- NetBIOS name
+- Fully qualified directory server name and port
+
+> [!TIP]
+>
+> - You can use `GC://` prefix to search in the Global Catalog, e.g.: `-Server GC://myChildDomain`.
+> - Including the port to use with your query is valid using the syntax `<HOST>:<PORT>`, e.g.: `-Server myDC01:636`.
 
 ```yaml
 Type: String
@@ -134,28 +184,93 @@ Accept wildcard characters: False
 
 ### -Top
 
-{{ Fill Top Description }}
+The maximum number of objects you want to get the ACL from. The default value is `0`, meaning that the maximum number of object you will be getting the ACL from is determined by your LDAP filter or lack of it (all objects).
+
+See also [`DirectorySearcher.SizeLimit` Property](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.directorysearcher.sizelimit#system-directoryservices-directorysearcher-sizelimit).
 
 ```yaml
 Type: Int32
+Parameter Sets: Filter
+Aliases:
+
+Required: False
+Position: Named
+Default value: 0
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -AuthenticationTypes
+
+Specifies the authentication method to use. The default value is `Secure`.
+
+> [!NOTE]
+>
+> [`AuthenticationTypes`](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.authenticationtypes) is a Flags Enum, meaning that you can combine values, for example `-AuthenticationTypes 'Secure, FastBind'` is valid.
+
+```yaml
+Type: AuthenticationTypes
 Parameter Sets: (All)
 Aliases:
 
 Required: False
 Position: Named
+Default value: Secure
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+
+Specifies an Active Directory object by providing one of the following property values. The identifier in parentheses is the LDAP display name for the attribute.
+
+- A DistinguishedName
+- A GUID (`objectGuid`)
+- A SID (`objectSid`)
+- A sAMAccountName
+
+> [!TIP]
+>
+> This parameter takes pipeline input. You can pipe the output from [ActiveDirectory cmdlets](https://learn.microsoft.com/en-us/powershell/module/activedirectory) to this parameter whenever the output has an `objectGuid` or a `DistinguishedName` property.
+
+```yaml
+Type: String
+Parameter Sets: Identity
+Aliases:
+
+Required: True
+Position: Named
 Default value: None
+Accept pipeline input: True (ByPropertyName, ByValue)
+Accept wildcard characters: False
+```
+
+### -PageSize
+
+Determines the maximum number of objects the server can return in a paged search. The default is `1000`.
+
+See also [`DirectorySearcher.PageSize` Property](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.directorysearcher.pagesize) for more details.
+
+```yaml
+Type: Int32
+Parameter Sets: Filter
+Aliases:
+
+Required: False
+Position: Named
+Default value: 1000
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ProgressAction
+### -SearchBase
 
-{{ Fill ProgressAction Description }}
+Specifies the `DistinguishedName` of an Organization Unit or Container as the base for your search.
 
 ```yaml
-Type: ActionPreference
-Parameter Sets: (All)
-Aliases: proga
+Type: String
+Parameter Sets: Filter
+Aliases:
 
 Required: False
 Position: Named
@@ -166,15 +281,17 @@ Accept wildcard characters: False
 
 ### CommonParameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
-### None
+### System.String
 
 ## OUTPUTS
 
-### System.Object
+### ADEffectiveAccess.EffectiveAccessRule
+
+### ADEffectiveAccess.EffectiveAuditRule
 
 ## NOTES
 

src/ADEffectiveAccess/DirectoryEntryBuilder.cs

@@ -39,11 +39,14 @@ internal DirectoryEntry Create(string? server = null, string? searchBase = null)
         string? path = (server, searchBase) switch
         {
             (null, null) => null,
-            (not null, null) => $"LDAP://{server}",
-            (null, not null) => $"LDAP://{searchBase}",
-            _ => $"LDAP://{server}/{searchBase}"
+            (not null, null) => server,
+            (null, not null) => searchBase,
+            _ => $"{server}/{searchBase}"
         };
 
+        if (path is not null && !path.Contains("://"))
+            path = $"LDAP://{path}";
+
         return new DirectoryEntry(path, _username, _password, _authenticationTypes);
     }