🎆 Sharpdown

A polyglot commenting language for generated markdown from code comments

Language	File Types
`CSharp`	.cs
`Sql`	.sql
`JavaScript`	.js, .mjs, .ts, .tsx
`PowerShell`	.ps1, .psm1

ConvertTo-RedactedPath

function ConvertTo-RedactedPath

Swap the user's home directory for ~ so log lines never spill private paths.

Parameters

[string]: Path
- Path to redact.

Returns

[string]
- Same path with $HOME replaced by ~.

Convert-SharpDownContent

function Convert-SharpDownContent

Stream a source file's marker comments and declaration lines as Markdown.

Parameters

[string]: Source
- Path to the source file.
[hashtable]: Config
- Language entry from $script:SharpDownConfig.
[switch]: API
- Suppress auto-generated declaration fences. Only marker lines emit.

Key	Description
`Marker`	The line prefix that signals a doc comment.
`Fence`	The code fence label applied to declarations.
`DeclPattern`	The regex that marks a line as a declaration.

Read and trim each source line so the tests ignore indentation.

A marker line is doc text: emit it with the prefix removed.
Otherwise a declaration line becomes a fenced signature, unless -API.
Drop the trailing brace so the fence holds just the declaration.
Fence the cleaned signature with the language's label.

Returns

[string[]]
- Doc lines, with declarations fenced unless -API is set.

Resolve-SharpDownTarget

function Resolve-SharpDownTarget

Compute the mirrored Markdown output path for a source file under -Recurse.

Parameters

[string]: Root
- Walk root passed to -Recurse.
[string]: Source
- Absolute path of the source file.
[string]: ProjectName
- Leaf of Root. Stripped if it leads the relative path.
[string]: OutRoot
- Output root passed as -OutPath.

Returns

[string]
- Absolute path of the .md to write.

Write-SharpDownFile

function Write-SharpDownFile

Convert a single source file and write the result. Skips with a warning when the source has no SharpDown content. Creates the output directory on demand.

Parameters

[string]: Source
- Path to the source file.
[string]: Target
- Path of the .md to write.
[hashtable]: Config
- Language entry from $script:SharpDownConfig.
[switch]: API
- Forwarded to Convert-SharpDownContent. Suppresses auto-fenced declarations.

Returns

[PSCustomObject]
- [string]: Source
  - Redacted source path.
- [string]: Target
  - Redacted target path.
- [int]: Lines
  - Number of lines emitted to the target.

Invoke-SharpDownFile

function Invoke-SharpDownFile

Validate the File-mode contract and convert one source.

Parameters

[string]: Path
- Source file path. Must be a leaf.
[string]: OutPath
- Target .md path. Must not be an existing directory.
[hashtable]: Config
- Language entry from $script:SharpDownConfig.
[switch]: API
- Forwarded to Write-SharpDownFile.

Throws

When Path is not a file.
When OutPath resolves to an existing directory.

Invoke-SharpDownTree

function Invoke-SharpDownTree

Validate the Directory-mode contract and walk a source tree.

Parameters

[string]: Path
- Source root. Must be a directory.
[string]: OutPath
- Output root. Must not be an existing file.
[hashtable]: Config
- Language entry from $script:SharpDownConfig.
[string]: Language
- Language name used in the no-files warning.
[switch]: API
- Forwarded to Write-SharpDownFile for each source file under the tree.

Throws

When Path is not a directory.
When OutPath resolves to an existing file. | Key | Description | | --- | --- | | Extensions | The set of file extensions walked under -Recurse. | | ExcludeRegex | The directory pattern skipped under -Recurse. |

ConvertTo-SharpDown

function ConvertTo-SharpDown

Public entry point. Convert a single source or a tree of sources to Markdown.

Two parameter sets:

File is the default. -Path is a single source file, -OutPath is the .md target.
Directory requires -Recurse. -Path is a source directory, -OutPath is the output root. -Path accepts pipeline input from Get-Item and Get-ChildItem -Directory.

Parameters

[string]: Language
- One of CSharp, Sql, JavaScript, PowerShell. Defaults to CSharp.
[string]: Path
- Source file in File set, source directory in Directory set. Pipeline-bound only in Directory set.
[string]: OutPath
- Output file in File set, output root in Directory set.
[switch]: Recurse
- Selects the Directory set.
[switch]: API
- Suppresses auto-generated declaration fences. Use for HTTP endpoint files where the doc IS the wire contract, not the language signatures.

Returns

[PSCustomObject[]]
- [string]: Source
  - Redacted source path.
- [string]: Target
  - Redacted target path.
- [int]: Lines
  - Number of lines emitted to the target.