CLI Documentation - Crossreferencing commands with related functions in Source code

[Daksol]

This issue has been raised in order to develop a mechanism which will reliably link CLI Commands to their underlying implmementation in the Perl Source. Several threads in Developer Forums showed interest for this.

Purpose of this Comment is to indicate direction this is taking, and request assistance with the CLI command exceptions where no obvious xref vs source is available.

Preparatory info gathering actions include:

• AAA Find Source xrefs for Notifications CLI commands where some info included in Request.pm, but that info does not include Source xref
• BBB Find Source xrefs for the CLI commands mentioned in Documentation but without info in Request.pm)
• CCC Review CLI commands included in Request.pm but not mentioned in documentation

Second stage will be to create some functionality which will (for minimal effort) keep these cross-references in line. Functionality may be automated - for instance by running a regular query thru source code. Will be amplified in future comment.

Relating CLI Commands to Source

Happily there is a ready source of information for maybe 90% of CLI commands, sub init{} on Request.pm.

Info on Request.pm

• See source file ../Slim/Control/Request.pm
• Within that file locate sub init{} (starts about line 450) which consists of a number of calls of addDispatch() which populates the Dispatch database on LMS startup.
• Commands in sub init{} are divided into two groups.
  • The main block which provides excellent xref vs source - example line addDispatch(['player', 'uuid', '_IDorIndex', '?'], [0, 1, 0, \&Slim::Control::Queries::playerXQuery]);
  • The "Notifications" commands where there is an addDispatch function call for each CLI command, but which does NOT include a reference to the source and related function - example line addDispatch(['playlist', 'newsong'], [1, 0, 0, undef]);
• Question - AAA - where can we find info on these Notifications commands?

CLI Commands in documentation but NOT on Request.pm

• Note though that there are further CLI commands covered in the CLI Documentation which are NOT included in sub init{}. These include:-
  • Mentioned in General - reference/cli/general.md
    • can
    • exit
    • listen
    • login
    • subscribe
  • Mentioned in Notifications - reference/cli/notifications.md
    • favorites changes
    • getexternalvolumeinfo
• Question - BBB - where can we find info on these commands?
  • Is there a separate mechanism here to get them into the system? I searched code base but did not locate more addDispatch() type function calls,

Commands mentioned in Request.pm with a line in sub init{}, but not in documentation

• Question - CCC - are these all current, not deprecated? Any place where there may be documentation on these?

  • which section do they belong in (General, Notifications, Players, Database, Notifications, Alarms, Compound Queries)

• Commands in main block of sub init{}

  • artwork - addDispatch(['artwork', '_artworkid'], [0, 0, 0, \&Slim::Control::Queries::showArtwork]);
    • Note that there is a command artworkspec included in General CLI
    • artwork is mentioned in Database comment section in Request.pm
  • contextmenu - addDispatch(['contextmenu', '_index', '_quantity'], [1, 1, 1, \&Slim::Control::Queries::contextMenuQuery]);
  • rating - addDispatch(['rating', '_item', '?'], [0, 1, 0, \&Slim::Control::Commands::ratingCommand]);
    • rating is mentioned in Database comment section in Request.pm
  • rating - addDispatch(['rating', '_item', '_rating'], [0, 0, 0, \&Slim::Control::Commands::ratingCommand]);
    • rating is mentioned in Database comment section in Request.pm
  • works - addDispatch(['works', '_index', '_quantity'], [0, 1, 1, \&Slim::Control::Queries::worksQuery]);

Commands in Notifictions block of sub init{}

• displaynotify - addDispatch(['displaynotify', '_type', '_parts', '_duration'], [1, 0, 0, undef]);
• fwdownloaded - addDispatch(['fwdownloaded', '_machine'], [0, 0, 0, undef]);
• newmetadata - addDispatch(['newmetadata'], [1, 0, 0, undef]);