0.14.2 puts Example explanation inside code block (0.14.1 doesn't!)

DEberhardt commented 2 years ago

Prerequisites

[X] Write a descriptive title.
[X] Make sure you are able to repro it on the latest released version
[X] Search the existing issues.

Steps to reproduce

here is my function:

function Connect-Me {
  <#
  .SYNOPSIS
    Connect to AzureAd, MicrosoftTeams and optionally also to Exchange
  .DESCRIPTION
    One function to connect them all.
    This CmdLet solves the requirement for individual authentication prompts for AzureAD and MicrosoftTeams
    (and optionally also to ExchangeOnline) when multiple connections are required.
  .PARAMETER AccountId
    Required. UserPrincipalName or LoginName of the Office365 Administrator
  .PARAMETER ExchangeOnline
    Optional. Connects to Exchange Online Management. Requires Exchange Admin Role
  .PARAMETER NoFeedback
    Optional. Suppresses output session information about established sessions. Used for calls by other functions
  .EXAMPLE
    Connect-Me [-AccountId] admin@domain.com
    Creates a session to AzureAD prompting for a Password for 'admin@domain.com'
    If AzureAdPreview is loaded, tries to enable eligible Admin roles in Privileged Identity Management
    Creates a session to MicrosoftTeams with the AzureAd Session details
    If unsuccessful, prompting for selection of the authenticated User only (no additional authentication needed)
  .EXAMPLE
    Connect-Me -AccountId admin@domain.com -NoFeedBack
    If AzureAdPreview is loaded, tries to enable eligible Admin roles in Privileged Identity Management
    Creates a session to MicrosoftTeams with the AzureAd Session details
    If unsuccessful, prompting for selection of the authenticated User only (no additional authentication needed)
    Does not display Session Information Object at the end - This is useful if called by other functions.
  [...]
}

Expected behavior

--- this is the output of v0.14.1

EXAMPLES

EXAMPLE 1

Connect-Me [-AccountId] admin@domain.com

Creates a session to AzureAD prompting for a Password for 'admin@domain.com' If AzureAdPreview is loaded, tries to enable eligible Admin roles in Privileged Identity Management Creates a session to MicrosoftTeams with the AzureAd Session details If unsuccessful, prompting for selection of the authenticated User only (no additional authentication needed)

Actual behavior

--- this is the output of v0.14.2

EXAMPLES

EXAMPLE 1

Connect-Me [-AccountId] admin@domain.com
Creates a session to AzureAD prompting for a Password for 'admin@domain.com'
If AzureAdPreview is loaded, tries to enable eligible Admin roles in Privileged Identity Management
Creates a session to MicrosoftTeams with the AzureAd Session details
If unsuccessful, prompting for selection of the authenticated User only (no additional authentication needed)

Error details

no error, just a style thing - don't think this is intentional

Environment data

❯ Get-Module Platyps -ListAvailable

    Directory: C:\Users\David\Documents\PowerShell\Modules

ModuleType Version    PreRelease Name                                PSEdition ExportedCommands
---------- -------    ---------- ----                                --------- ----------------
Script     0.14.2                platyPS                             Desk      {New-MarkdownHelp, Get-MarkdownMetadata…

❯ $Psversiontable

Name                           Value
----                           -----
PSVersion                      7.2.5
PSEdition                      Core
GitCommitId                    7.2.5
OS                             Microsoft Windows 10.0.22621
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Visuals

v0.14.1 on the left v0.14.2 in the middle Preview of new file on the right.

sdwheeler commented 2 years ago

I think this is expected behavior. You need a blank line between the code and the text in your comment-based help.

sdwheeler commented 2 years ago

Adding a blank line after the code fixes the issue. PlatyPS needs the blank line to tell where the code stops and the paragraph begins.

PowerShell / platyPS