Skip to content

Commit 4c13d1f

Browse files
MariusStorhaugMariusStorhaug
authored
🩹 [Patch]: Enhance documentation for functions (#37)
## Description This pull request includes significant updates to the font management functions in the PowerShell module, enhancing their functionality and documentation. The key changes include improved descriptions, added examples with outputs, and support for additional parameters. ### Enhancements to `Get-Font` function: * Updated the description to clarify the retrieval of installed fonts with support for filtering by font name using wildcards. * Added example outputs to illustrate the function's usage and expected results. * Included detailed notes on the returned font object properties and a link to the function's documentation. ### Enhancements to `Install-Font` function: * Improved the description to include details on scope, force installation, and batch installations via pipeline input. * Added example outputs to demonstrate the function's behavior in different scenarios, including single file and batch installations. * Changed the `Scope` parameter type from `Scope[]` to `string` for better clarity and usage. * Included notes on the function's outputs and a link to the documentation. ### Enhancements to `Uninstall-Font` function: * Updated the description to include support for removing fonts for either the current user or all users, with administrative privileges required for the latter. * Added example outputs to show the verbose logging during font uninstallation. * Included notes on the function's behavior and a link to the documentation. ## Type of change <!-- Use the check-boxes [x] on the options that are relevant. --> - [x] 📖 [Docs] - [ ] 🪲 [Fix] - [x] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [ ] 🚀 [Feature] - [ ] 🌟 [Breaking change] ## Checklist <!-- Use the check-boxes [x] on the options that are relevant. --> - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas
1 parent b746cb0 commit 4c13d1f

3 files changed

Lines changed: 159 additions & 48 deletions

File tree

‎src/functions/public/Get-Font.ps1‎

Lines changed: 51 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,33 +3,73 @@
33
function Get-Font {
44
<#
55
.SYNOPSIS
6-
Retrieves the installed fonts.
6+
Retrieves the installed fonts.
77
88
.DESCRIPTION
9-
Retrieves the installed fonts.
9+
Retrieves a list of installed fonts for the current user or all users, depending on the specified scope.
10+
Supports filtering by font name using wildcards.
1011
1112
.EXAMPLE
12-
Get-Font
13+
Get-Font
1314
14-
Gets all the fonts installed for the current user.
15+
Output:
16+
```powershell
17+
Name Path Scope
18+
---- ---- -----
19+
Arial C:\Windows\Fonts\arial.ttf CurrentUser
20+
```
21+
22+
Gets all the fonts installed for the current user.
1523
1624
.EXAMPLE
17-
Get-Font -Name 'Arial*'
25+
Get-Font -Name 'Arial*'
26+
27+
Output:
28+
```powershell
29+
Name Path Scope
30+
---- ---- -----
31+
Arial C:\Windows\Fonts\arial.ttf CurrentUser
32+
Arial Bold C:\Windows\Fonts\arialbd.ttf CurrentUser
33+
```
1834
19-
Gets all the fonts installed for the current user that start with 'Arial'.
35+
Gets all the fonts installed for the current user that start with 'Arial'.
2036
2137
.EXAMPLE
22-
Get-Font -Scope 'AllUsers'
38+
Get-Font -Scope 'AllUsers'
39+
40+
Output:
41+
```powershell
42+
Name Path Scope
43+
---- ---- -----
44+
Calibri C:\Windows\Fonts\calibri.ttf AllUsers
45+
```
2346
24-
Gets all the fonts installed for all users.
47+
Gets all the fonts installed for all users.
2548
2649
.EXAMPLE
27-
Get-Font -Name 'Calibri' -Scope 'AllUsers'
50+
Get-Font -Name 'Calibri' -Scope 'AllUsers'
2851
29-
Gets the font with the name 'Calibri' for all users.
52+
Output:
53+
```powershell
54+
Name Path Scope
55+
---- ---- -----
56+
Calibri C:\Windows\Fonts\calibri.ttf AllUsers
57+
```
58+
59+
Gets the font with the name 'Calibri' for all users.
3060
3161
.OUTPUTS
32-
[System.Collections.Generic.List[PSCustomObject]]
62+
System.Collections.Generic.List[PSCustomObject]
63+
64+
.NOTES
65+
Returns a list of installed fonts.
66+
Each font object contains properties:
67+
- Name: The font name.
68+
- Path: The full file path to the font.
69+
- Scope: The scope from which the font is retrieved.
70+
71+
.LINK
72+
https://psmodule.io/Font/Functions/Get-Font
3373
#>
3474
[Alias('Get-Fonts')]
3575
[OutputType([System.Collections.Generic.List[PSCustomObject]])]

‎src/functions/public/Install-Font.ps1‎

Lines changed: 76 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,56 +3,105 @@
33
function Install-Font {
44
<#
55
.SYNOPSIS
6-
Installs a font in the system
6+
Installs a font in the system.
77
88
.DESCRIPTION
9-
Installs a font in the system
9+
Installs a font in the system, either for the current user or all users, depending on the specified scope.
10+
If the font is already installed, it can be optionally overwritten using the `-Force` parameter.
11+
The function supports both single file installations and batch installations via pipeline input.
12+
13+
Installing fonts for all users requires administrator privileges.
1014
1115
.EXAMPLE
12-
Install-Font -Path C:\FontFiles\Arial.ttf
16+
Install-Font -Path C:\FontFiles\Arial.ttf
17+
18+
Output:
19+
```powershell
20+
Arial.ttf installed for the current user.
21+
```
1322
14-
Installs the font file 'C:\FontFiles\Arial.ttf' to the current user profile.
23+
Installs the font file `Arial.ttf` for the current user.
1524
1625
.EXAMPLE
17-
Install-Font -Path C:\FontFiles\Arial.ttf -Scope AllUsers
26+
Install-Font -Path C:\FontFiles\Arial.ttf -Scope AllUsers
27+
28+
Output:
29+
```powershell
30+
Arial.ttf installed for all users.
31+
```
1832
19-
Installs the font file 'C:\FontFiles\Arial.ttf' so it is available for all users.
20-
This requires administrator rights.
33+
Installs the font file `Arial.ttf` system-wide, making it available to all users.
34+
This requires administrator rights.
2135
2236
.EXAMPLE
23-
Install-Font -Path C:\FontFiles\Arial.ttf -Force
37+
Install-Font -Path C:\FontFiles\Arial.ttf -Force
2438
25-
Installs the font file 'C:\FontFiles\Arial.ttf' to the current user profile.
26-
If the font already exists, it will be overwritten.
39+
Output:
40+
```powershell
41+
Arial.ttf reinstalled for the current user.
42+
```
43+
44+
Installs the font file `Arial.ttf` for the current user. If it already exists, it will be overwritten.
2745
2846
.EXAMPLE
29-
Install-Font -Path C:\FontFiles\Arial.ttf -Scope AllUsers -Force
47+
Install-Font -Path C:\FontFiles\Arial.ttf -Scope AllUsers -Force
48+
49+
Output:
50+
```powershell
51+
Arial.ttf reinstalled for all users.
52+
```
3053
31-
Installs the font file 'C:\FontFiles\Arial.ttf' so it is available for all users.
32-
This requires administrator rights. If the font already exists, it will be overwritten.
54+
Installs the font file `Arial.ttf` system-wide and overwrites the existing font if present.
3355
3456
.EXAMPLE
35-
Get-ChildItem -Path C:\FontFiles\ -Filter *.ttf | Install-Font
57+
Get-ChildItem -Path C:\FontFiles\ -Filter *.ttf | Install-Font
3658
37-
Gets all font files in the folder 'C:\FontFiles\' and installs them to the current user profile.
59+
Output:
60+
```powershell
61+
Found 3 font files.
62+
Arial.ttf installed for the current user.
63+
Verdana.ttf installed for the current user.
64+
TimesNewRoman.ttf installed for the current user.
65+
```
66+
67+
Installs all `.ttf` font files found in `C:\FontFiles\` for the current user.
3868
3969
.EXAMPLE
40-
Get-ChildItem -Path C:\FontFiles\ -Filter *.ttf | Install-Font -Scope AllUsers
70+
Get-ChildItem -Path C:\FontFiles\ -Filter *.ttf | Install-Font -Scope AllUsers
71+
72+
Output:
73+
```powershell
74+
Found 3 font files.
75+
Arial.ttf installed for all users.
76+
Verdana.ttf installed for all users.
77+
TimesNewRoman.ttf installed for all users.
78+
```
4179
42-
Gets all font files in the folder 'C:\FontFiles\' and installs them so it is available for all users.
43-
This requires administrator rights.
80+
Installs all `.ttf` font files found in `C:\FontFiles\` system-wide.
81+
This requires administrator rights.
4482
4583
.EXAMPLE
46-
Get-ChildItem -Path C:\FontFiles\ -Filter *.ttf | Install-Font -Force
84+
Get-ChildItem -Path C:\FontFiles\ -Filter *.ttf | Install-Font -Scope AllUsers -Force
4785
48-
Gets all font files in the folder 'C:\FontFiles\' and installs them to the current user profile.
49-
If the font already exists, it will be overwritten.
86+
Output:
87+
```powershell
88+
Found 3 font files.
89+
Arial.ttf reinstalled for all users.
90+
Verdana.ttf reinstalled for all users.
91+
TimesNewRoman.ttf reinstalled for all users.
92+
```
5093
51-
.EXAMPLE
52-
Get-ChildItem -Path C:\FontFiles\ -Filter *.ttf | Install-Font -Scope AllUsers -Force
94+
Installs all `.ttf` font files found in `C:\FontFiles\` system-wide, overwriting existing fonts.
95+
This requires administrator rights.
96+
97+
.OUTPUTS
98+
System.String
99+
100+
.NOTES
101+
Returns messages indicating success or failure of font installation.
53102
54-
Gets all font files in the folder 'C:\FontFiles\' and installs them so it is available for all users.
55-
This requires administrator rights. If the font already exists, it will be overwritten.
103+
.LINK
104+
https://psmodule.io/Admin/Functions/Install-Font/
56105
#>
57106
[Alias('Install-Fonts')]
58107
[CmdletBinding(SupportsShouldProcess)]
@@ -70,13 +119,13 @@ function Install-Font {
70119
# CurrentUser will install the font for the current user only.
71120
# AllUsers will install the font so it is available for all users on the system.
72121
[Parameter(ValueFromPipelineByPropertyName)]
73-
[Scope[]] $Scope = 'CurrentUser',
122+
[string] $Scope = 'CurrentUser',
74123

75124
# Recurse will install all fonts in the specified folder and subfolders.
76125
[Parameter()]
77126
[switch] $Recurse,
78127

79-
# Force will overwrite existing fonts
128+
# Force will overwrite existing fonts.
80129
[Parameter()]
81130
[switch] $Force
82131
)

‎src/functions/public/Uninstall-Font.ps1‎

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,47 @@
1-
#Requires -Modules @{ ModuleName = 'Admin'; RequiredVersion = '1.1.3' }
2-
3-
function Uninstall-Font {
1+
function Uninstall-Font {
42
<#
53
.SYNOPSIS
6-
Uninstalls a font from the system.
4+
Uninstalls a font from the system.
75
86
.DESCRIPTION
9-
Uninstalls a font from the system.
7+
Uninstalls a font from the system. The function supports removing fonts for either the current user
8+
or all users. If attempting to remove a font for all users, administrative privileges are required.
9+
The function ensures font files are deleted, and if on Windows, it also unregisters fonts from the registry.
1010
1111
.EXAMPLE
12-
Uninstall-Font -Name 'Courier New'
12+
Uninstall-Font -Name 'Courier New'
13+
14+
Output:
15+
```powershell
16+
VERBOSE: [Uninstall-Font] - [CurrentUser] - [Courier New] - Processing
17+
VERBOSE: [Uninstall-Font] - [CurrentUser] - [Courier New] - Removing file [C:\Windows\Fonts\cour.ttf]
18+
VERBOSE: [Uninstall-Font] - [CurrentUser] - [Courier New] - Unregistering font [Courier New]
19+
VERBOSE: [Uninstall-Font] - [CurrentUser] - [Courier New] - Done
20+
```
1321
14-
Uninstalls the 'Courier New' font from the system for the current user.
22+
Uninstalls the 'Courier New' font from the system for the current user.
1523
1624
.EXAMPLE
17-
Uninstall-Font -Name 'Courier New' -Scope AllUsers
25+
Uninstall-Font -Name 'Courier New' -Scope AllUsers
26+
27+
Output:
28+
```powershell
29+
VERBOSE: [Uninstall-Font] - [AllUsers] - [Courier New] - Processing
30+
VERBOSE: [Uninstall-Font] - [AllUsers] - [Courier New] - Removing file [C:\Windows\Fonts\cour.ttf]
31+
VERBOSE: [Uninstall-Font] - [AllUsers] - [Courier New] - Unregistering font [Courier New]
32+
VERBOSE: [Uninstall-Font] - [AllUsers] - [Courier New] - Done
33+
```
1834
19-
Uninstalls the Courier New font from the system for all users.
35+
Uninstalls the 'Courier New' font from the system for all users. Requires administrative privileges.
2036
2137
.OUTPUTS
22-
None
38+
None
39+
40+
.NOTES
41+
The function does not return any objects.
42+
43+
.LINK
44+
https://psmodule.io/Admin/Functions/Uninstall-Font/
2345
#>
2446
[Alias('Uninstall-Fonts')]
2547
[CmdletBinding()]

0 commit comments

Comments
 (0)