Documentation

[mawosoft]

Contributes to #5. Closes #74.

[codecov[bot]]

Codecov Report

Merging #72 (dad4657) into master (996fc90) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #72   +/-   ##
=======================================
  Coverage   94.84%   94.84%           
=======================================
  Files          73       73           
  Lines        3005     3005           
  Branches      275      275           
=======================================
  Hits         2850     2850           
  Misses         48       48           
  Partials      107      107           

Files Changed	Coverage Δ
...Shell.WindowsSearchManager/AddSearchRootCommand.cs	91.17% <ø> (ø)
...Shell.WindowsSearchManager/AddSearchRuleCommand.cs	94.91% <ø> (ø)
...ll.WindowsSearchManager/GetSearchCatalogCommand.cs	100.00% <ø> (ø)
...ll.WindowsSearchManager/GetSearchManagerCommand.cs	88.88% <ø> (ø)
...Shell.WindowsSearchManager/GetSearchRootCommand.cs	96.00% <ø> (ø)
...Shell.WindowsSearchManager/GetSearchRuleCommand.cs	94.44% <ø> (ø)
...WindowsSearchManager/RemoveSearchCatalogCommand.cs	85.71% <ø> (ø)
...ll.WindowsSearchManager/RemoveSearchRootCommand.cs	90.47% <ø> (ø)
...ll.WindowsSearchManager/RemoveSearchRuleCommand.cs	92.85% <ø> (ø)
....WindowsSearchManager/ResetSearchCatalogCommand.cs	90.90% <ø> (ø)
... and 10 more

[mawosoft]

• Consider removing <summary> comment from POCO properties and use only <value>. Both together are pretty redundant, although it seems to be common practice. DocFx layout is roughly:

  FooBar

  The summary text or nothing if summary is omitted.

  Declaration

  public bool FooBar { get; set; }

  Property Value

  Type	Description
  bool	The value text or nothing if value is omitted.

  Remarks

  The remarks text or nothing (and no header either) if remarks is omitted.

• Should we post-process MAML for [!NOTE] and similar tags?

  • Markdown

    > [!NOTE]
    > Something noteworthy goes here.

  • GitHub supports some of them

    [!NOTE] Something noteworthy goes here.

  • Get-Help will show:

    > [!NOTE] > Something noteworthy goes here.

    unless [!NOTE] is followed by two spaces (backslash won't work) to force a line break:

    > [!NOTE]
    > Something noteworthy goes here.

• PowerShell verbiage for admin required: Sometimes in Description, sometimes in Notes, mostly as simple paragraph in both cases, but sometimes tagged with [!NOTE].

  • You must run this cmdlet from an elevated PowerShell session.
  • Set-Service requires elevated permissions. Use the Run as administrator option.
  • To run this cmdlet, start PowerShell by using the Run as administrator option.
  • On Windows, the IncludeUserName parameter requires elevated user rights (Run as Administrator).