Skip to content

Commit fdedf80

Browse files
MariusStorhaugMariusStorhaug
committed
Match the GitHub module comment-based help style and link each command to its docs page
Indent the help sections and add blank lines between them, wrap examples in fenced powershell blocks with a short description, and make the first .LINK each public command's documentation page (https://psmodule.io/Confluence/Functions/<Area>/<Command>/). Atlassian API references follow as additional .LINK entries. Private helpers are indented too but keep no docs link.
1 parent 04ae285 commit fdedf80

39 files changed

Lines changed: 498 additions & 146 deletions

‎src/functions/private/Auth/Resolve-ConfluenceContext.ps1‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
function Resolve-ConfluenceContext {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Resolve a context argument into a usable credential-context object.
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Accepts a context object/hashtable (returned as-is), a context name
78
(looked up in the vault), or nothing (falls back to the default context
89
recorded in the module configuration).

‎src/functions/private/Auth/Resolve-ConfluenceToken.ps1‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
function Resolve-ConfluenceToken {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Return the plain-text API token from a SecureString or string.
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
The token is stored as a SecureString in the credential context; this
78
converts it to the plain text needed to build the Basic auth header.
89
#>

‎src/functions/private/Config/ConvertTo-ConfluenceHashtable.ps1‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
function ConvertTo-ConfluenceHashtable {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Convert a PSCustomObject (or hashtable) into a plain hashtable.
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Used to turn the stored module-configuration context returned by
78
Get-Context into a mutable hashtable.
89
#>

‎src/functions/private/Config/Initialize-ConfluenceConfig.ps1‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
function Initialize-ConfluenceConfig {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Load the module configuration from the context vault into memory.
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Loads the stored 'Module' configuration context, creating it from the
78
built-in defaults on first use. Missing default keys are backfilled.
89
#>

‎src/functions/public/API/Invoke-ConfluenceRestMethod.ps1‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@
33

44
function Invoke-ConfluenceRestMethod {
55
<#
6-
.SYNOPSIS
6+
.SYNOPSIS
77
Call the Confluence REST API using a stored (or supplied) context.
8-
.DESCRIPTION
8+
9+
.DESCRIPTION
910
The single generic entry point that every other Confluence function is
1011
built on. It resolves the credential context, builds the HTTP Basic auth
1112
header, sends the request, and surfaces API errors as terminating errors.
@@ -16,11 +17,21 @@ function Invoke-ConfluenceRestMethod {
1617
rejection from other failures. Pass -Debug to emit the full request and
1718
response (status, headers, and body); the Authorization header is
1819
redacted.
19-
.EXAMPLE
20+
21+
.EXAMPLE
22+
```powershell
2023
Invoke-ConfluenceRestMethod -ApiEndpoint '/wiki/api/v2/spaces' -Query @{ limit = 1 }
21-
.LINK
24+
```
25+
26+
Calls the spaces endpoint directly and returns the raw response.
27+
28+
.LINK
29+
https://psmodule.io/Confluence/Functions/API/Invoke-ConfluenceRestMethod/
30+
31+
.LINK
2232
https://developer.atlassian.com/cloud/confluence/rest/v2/intro/
23-
.LINK
33+
34+
.LINK
2435
https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/
2536
#>
2637
[CmdletBinding()]

‎src/functions/public/Attachments/Add-ConfluenceAttachment.ps1‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,26 @@
11
function Add-ConfluenceAttachment {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Upload an attachment to a page (read:content-details and write:attachment).
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Uploads a file as a page attachment. Confluence exposes attachment
78
creation only on the v1 content endpoint
89
(/wiki/rest/api/content/{id}/child/attachment), which requires BOTH
910
read:content-details and write:attachment. A token with write:attachment
1011
but without read:content-details is rejected with a scope-check 401.
11-
.EXAMPLE
12+
13+
.EXAMPLE
14+
```powershell
1215
Add-ConfluenceAttachment -PageId '12345' -Path ./diagram.png
13-
.LINK
16+
```
17+
18+
Uploads diagram.png as an attachment on page 12345.
19+
20+
.LINK
21+
https://psmodule.io/Confluence/Functions/Attachments/Add-ConfluenceAttachment/
22+
23+
.LINK
1424
https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content---attachments/
1525
#>
1626
[CmdletBinding(SupportsShouldProcess)]

‎src/functions/public/Attachments/Get-ConfluenceAttachment.ps1‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,22 @@
11
function Get-ConfluenceAttachment {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Get page attachments (read:attachment).
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Lists the attachments on a page, or returns a single attachment by id.
7-
.EXAMPLE
8+
9+
.EXAMPLE
10+
```powershell
811
Get-ConfluenceAttachment -PageId '12345'
9-
.LINK
12+
```
13+
14+
Lists the attachments on page 12345.
15+
16+
.LINK
17+
https://psmodule.io/Confluence/Functions/Attachments/Get-ConfluenceAttachment/
18+
19+
.LINK
1020
https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-attachment/
1121
#>
1222
[CmdletBinding(DefaultParameterSetName = 'ByPage')]

‎src/functions/public/Attachments/Remove-ConfluenceAttachment.ps1‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,22 @@
11
function Remove-ConfluenceAttachment {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Delete an attachment (delete:attachment).
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Deletes an attachment by id.
7-
.EXAMPLE
8+
9+
.EXAMPLE
10+
```powershell
811
Remove-ConfluenceAttachment -AttachmentId 'att12345'
9-
.LINK
12+
```
13+
14+
Deletes the attachment with ID att12345.
15+
16+
.LINK
17+
https://psmodule.io/Confluence/Functions/Attachments/Remove-ConfluenceAttachment/
18+
19+
.LINK
1020
https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-attachment/
1121
#>
1222
[CmdletBinding(SupportsShouldProcess)]

‎src/functions/public/Auth/Connect-Confluence.ps1‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,29 @@
11
function Connect-Confluence {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Connect to Confluence and store a credential profile in the context vault.
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Validates the supplied credentials with a lightweight authenticated call,
78
stores them as a named context (the token is kept as a SecureString), and
89
records the context as the module default. A token that authenticates but
910
lacks the read:space scope still connects (with a warning).
10-
.EXAMPLE
11+
12+
.EXAMPLE
13+
```powershell
1114
$token = Read-Host -AsSecureString
1215
Connect-Confluence -ApiBaseUri $uri -Username $user -Token $token -SpaceKey 'DOCS'
13-
.LINK
16+
```
17+
18+
Connects with a scoped token and stores the profile with 'DOCS' as the default space.
19+
20+
.LINK
21+
https://psmodule.io/Confluence/Functions/Auth/Connect-Confluence/
22+
23+
.LINK
1424
https://developer.atlassian.com/cloud/confluence/rest/v2/intro/#auth
15-
.LINK
25+
26+
.LINK
1627
https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/
1728
#>
1829
[CmdletBinding(SupportsShouldProcess)]

‎src/functions/public/Auth/Disconnect-Confluence.ps1‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
11
function Disconnect-Confluence {
22
<#
3-
.SYNOPSIS
3+
.SYNOPSIS
44
Remove a stored Confluence credential profile.
5-
.DESCRIPTION
5+
6+
.DESCRIPTION
67
Deletes the named context from the vault and clears it as the default
78
context if it was the current default.
8-
.EXAMPLE
9+
10+
.EXAMPLE
11+
```powershell
912
Disconnect-Confluence -Name 'sandbox'
13+
```
14+
15+
Removes the stored 'sandbox' credential profile.
16+
17+
.LINK
18+
https://psmodule.io/Confluence/Functions/Auth/Disconnect-Confluence/
1019
#>
1120
[CmdletBinding(SupportsShouldProcess)]
1221
param(

0 commit comments

Comments
 (0)