Empty file causes errors

[PrzemyslawKlys]

Steps to reproduce

1. Generate docs
2. Go into one file .md that was generated
3. Remove its content and leave it empty
4. Rerun generation

Expected behavior

No errors, overwrite.

Actual behavior

While shouldn't really happen, it happens for me when I cancel docs generation and regenerate them. Sometimes .MD file is empty and thigns fail.

[vors]

Can you be more precise, is it New-MarkdownHelp call or Update-MarkdownHelp call? If the former, that's expected and no way around it: it has to update the existing documentation, so if it doesn't exist then...

[PrzemyslawKlys]

Well, the current way it works is if the file doesn't exist it will create it. If the file exists but is empty it will throw errors that don't point you to any direction. Just a bunch of mumbo jumbo and a goose chase. It actually took me a while to understand what happened and why. It wasn't the first time and on the first time I actually gave up and removed everything.

My proposal would be:

1. If a file exists and it's empty it would delete it and recreate it
2. If a file exists and has content it would display a warning where / what happened and gracefully terminate for that file

In the current state, it's very confusing and hard to "fix" my mistake/problem.

PS. It's Update-MarkdownHelpModule

[vors]

Ah I see. Yes, the (1) makes total sense. Actually I think that #438 should fix that problem, can you please try a fresh build from master (you can grab it from CI)?

[PrzemyslawKlys]

Well I've not tested yet but seeing the change

if ( -not ($updatedCommands -contains $_) 

Which basically implies that if a file isn't there use -Force. At least that's how I understand it. But it actually is in there. Just empty, so it would be skipped anyway. There needs to be another condition in there checking for size and if 0 it would run -Force on it as well.

[vors]

If file is not there, there is no need to use -Force. Check the original task #437, I'm fairly sure this is fixed.

[vors]

Actually on the second though, it may be different indeed. I think you should try out and implement (1), that's like 2 lines change.

[PrzemyslawKlys]

Sure, I'll give it a try but I need to have my first PR approved/denied. I'm in a state where I can't do changes in VSCode anymore because my git-foo is preventing me from further work. I need to delete everything and start from scratch, would prefer not to. And in my other PR I don't know how to fix one test because it's failing and I don't understand why. So if you could help with that, point me in the right direction I can give it a go.

[vors]

Oh sorry, the test failure was unrelated to your change #439 - it's the same on master. (we should probably delete this test to avoid any confusion)

I have a favorite git learning resource, I recommend to everyone who wants to master git in few hours: https://github.com/Gazler/githug It's super good and setted up as a game with something like 50 levels. Very addictive!

[sdwheeler]

Tested with 0.14.2 using the platyps markdown help files.

1. Deleted the contents of New-YamlHelp.md.
2. Ran Update-MarkdownHelp

Results - The New-YamlHelp.md file now contains the help for New-MarkdownHelp.md.

PS C:\temp\platyps\docs> Update-MarkdownHelp -Path . -UseFullTypeName -UpdateInputOutput -AlphabeticParamsOrder -LogPath .\log.txt                                                                                                                                                                                                                  Directory: C:\temp\platyps\docs                                                                                                                                                                                             Mode                 LastWriteTime         Length Name                                                          ----                 -------------         ------ ----
-a---            8/9/2021  8:52 AM           2856 Get-HelpPreview.md
-a---            8/9/2021  8:52 AM           3755 Get-MarkdownMetadata.md
-a---            8/9/2021  8:52 AM           4758 Merge-MarkdownHelp.md
-a---            8/9/2021  8:52 AM           7407 New-ExternalHelp.md
-a---            8/9/2021  8:52 AM           3710 New-ExternalHelpCab.md
-a---            8/9/2021  8:52 AM           2970 New-MarkdownAboutHelp.md
-a---            8/9/2021  8:52 AM          15666 New-MarkdownHelp.md
Get-MarkdownMetadata: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:1663
Line |
1663 |      $metadata = Get-MarkdownMetadata -markdown $markdown
     |                                                 ~~~~~~~~~
     | Cannot bind argument to parameter 'Markdown' because it is an empty string.

Get-Command: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:438
Line |
 438 |              $command = Get-Command $name -ErrorAction SilentlyContinu …
     |                                     ~~~~~
     | Cannot validate argument on parameter 'Name'. The argument is null or empty. Provide an
     | argument that is not null or empty, and then try the command again.

MethodInvocationException: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:356
Line |
 356 |  …             [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($m …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Exception calling "GetYamlMetadata" with "1" argument(s): "Object reference not set to an
     | instance of an object."

InvalidOperation: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:459
Line |
 459 |              $metadata["external help file"] = GetHelpFileName $comman …
     |              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Cannot index into a null array.

GetMamlObject: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:460                     Line |                                                                                                           460 |  … flectionModel = GetMamlObject -Session $Session -Cmdlet $name -UseFul …                                    |                                                            ~~~~~                                              | Cannot bind argument to parameter 'Cmdlet' because it is an empty string.                                                                                                                                                InvalidOperation: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:461
Line |
 461 |              $metadata[$script:MODULE_PAGE_MODULE_NAME] = $reflectionM …
     |              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Cannot index into a null array.

SortParamsAlphabetically: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:468
Line |
 468 |                  SortParamsAlphabetically $newModel
     |                                           ~~~~~~~~~
     | Cannot bind argument to parameter 'MamlCommandObject' because it is null.

ConvertMamlModelToMarkdown: C:\Users\sewhee\Documents\PowerShell\Modules\platyPS\0.14.2\platyPS.psm1:471
Line |
 471 |  …       $md = ConvertMamlModelToMarkdown -mamlCommand $newModel -metada …
     |                                                        ~~~~~~~~~
     | Cannot validate argument on parameter 'mamlCommand'. The argument is null or empty. Provide an
     | argument that is not null or empty, and then try the command again.

-a---            8/9/2021  8:59 AM          15666 New-YamlHelp.md
-a---            8/9/2021  8:52 AM           7907 Update-MarkdownHelp.md
-a---            8/9/2021  8:52 AM           8100 Update-MarkdownHelpModule.md

[theJasonHelmick]

Thank you for this issue - Discussed with @sdwheeler and we will further investigate how we will handle the error condition.

[sdwheeler]

This no longer applies in the new version. Open a new issue against the new version once it is released.