Document hook_layout_access_info and hook_layout_relationship_info

[argiepiano]

hook_layout_access_info and hook_layout_relationship_info are not documented anywhere. Other related hooks such as hook_layout_context_info() are - in layout.api.php, which would be a good place to document those missing ones.

[argiepiano]

PR backdrop/backdrop#4861 available for review.

[argiepiano]

@docwilmot you are so familiar with Layouts - would you please take a look at this documentation?

[docwilmot]

@argiepiano I think others may be better at finding the right ways to describe things, so I'll post my ideas here so they can chime in:

I've opted to remove the block that says "Each type of relationship requires a class..." since a class name is a required key anyway, so that seemed like a duplication (although hook_layout_context_info() says same it seems reasonable there as an explanation of how contexts work generally.)

/**
 * Provides information on access plugins available to Layout module.
 *
 * Each access plugin is available in the UI as a "visibility condition". 
 * These VCs allow site builders to restrict access to layouts according
 * to criteria determined by the plugin. VCs may be applied to entire 
 * layouts, to a menu path shared by multiple layouts, or to layout blocks. 
 * If the conditions specified by the VC are not met, access is denied to the 
 * layout, path or block.
 *
 * @return array
 *   An info array keyed by a unique machine name for that access plugin. Possible keys
 *   include:
 *   - title: The human-readable name of the context.
 *   - description: A description of what the access plugin does.
 *   - class: The name of a class to handle access. This class should
 *     extend the LayoutAccess class. The class should be registered in
 *     hook_autoload_info().
 *   - required contexts: (optional) An array of contexts required for this
 *     visibility condition. These contexts are keyed by their internal name
 *     that this plugin will receive. The value of each item should be the type
 *     of context, as listed by hook_layout_context_info().
 *   - required contexts labels: (optional) Provides human-readable labels for
 *     the required contexts. This is helpful when a plugin needs two or more
 *     contexts of the same type.
 *
 * @see hook_autoload_info()
 * @see layout_get_access_info() **added**
 * @see layout_layout_access_info()
 * @see LayoutAccess
 */
function hook_layout_access_info() 

And

/**
 * Provides information on context relationships available to Layout module.
 *
 * These plugins establish relationships between layout or block contexts,
 * allowing layouts to generate new contexts from existing contexts. 
 * For example, if a node context exists on a layout, relationship plugins 
 * are available that can extract a user context (the node author) from this. 
 * This allows site builders to create Visibility Conditions from these new
 * relationship contexts.
 *

 * @return array
 *   Each item in the returned array of info should have the following keys:
 *   - title: The human-readable name of the context.
 *   - description: A description of what the access plugin does.
 *   - class: The name of a class to handle access. This class should
 *     extend the LayoutAccess class. The class should be registered in
 *     hook_autoload_info().
 *   - context: The type of context from which this plugin is providing a
 *     relationship. These contexts are defined by hook_layout_context_info()
 *   - context_label: (optional) A human-readable label for the context.
 *
 * @see hook_autoload_info()
 * @see layout_get_relationship_info()
 * @see layout_layout_relationship_info()
 * @see LayoutRelationship
 */
function hook_layout_relationship_info()