% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/block-roclet.R
\name{block_roclet}
\alias{block_roclet}
\alias{block_registration_roclet}
\title{Block registration roclet}
\usage{
block_registration_roclet()
}
\value{
\code{block_registration_roclet()} returns a roclet object.
}
\description{
A custom roxygen2 roclet that turns block registration metadata, declared as
tags on block constructors, into a YAML registry (\code{inst/registry/blocks.yml})
that \code{\link[=register_package_blocks]{register_package_blocks()}} reads at load time. It runs alongside the
standard roclets during \code{\link[roxygen2:roxygenise]{roxygen2::roxygenise()}} (or \code{devtools::document()})
for any package that lists \code{blockr.core::block_registration_roclet} in the
\code{Roxygen} field of its \code{DESCRIPTION}.
}
\section{Tags}{

Placed in the roxygen block above a block constructor:
\describe{
\item{\verb{@block <name>}}{Human-readable block name. Required: its presence is
what marks a constructor for registration.}
\item{\verb{@blockDescr <text>}}{Short block description. Required.}
\item{\verb{@blockCategory <category>}}{One of the \code{\link[=suggested_categories]{suggested_categories()}}.
Required.}
\item{\verb{@blockIcon <icon>}}{Bootstrap icon name. Optional, defaulting to the
category icon (see \code{\link[=default_icon]{default_icon()}}).}
\item{\verb{@blockGuidance <text>}}{Model-facing construction guidance -- do and
don't rules, enumerations, pitfalls. Optional.}
\item{\verb{@blockKeywords <terms>}}{Comma-separated search terms for block
discovery; a term may contain spaces. Optional.}
\item{\verb{@blockDetails <text>}}{Longer human-facing description (e.g. for a
help popover). Optional; when omitted it falls back to the constructor's
\verb{@details} or, failing that, its \verb{@section} prose.}
\item{\verb{@blockLink <url>}}{URL of the block's help or documentation page.
Optional; when omitted it is derived from the package's pkgdown \code{url}
(\verb{_pkgdown.yml} or \code{DESCRIPTION}) and the documented topic, as
\verb{<url>/reference/<topic>.html}.}
\item{\verb{@blockArg <name> <description>}}{One constructor argument's
specification. The text after the name is a free-text description;
\verb{[example] <expr>} and \verb{[type] <expr>} markers (each on its own line)
supply an R expression -- evaluated when documentation is generated --
for a worked example value and an \verb{arg_*()} type descriptor (see
\code{\link[=new_block_arg]{new_block_arg()}}). An explicit \verb{[description] <text>} marker may replace
the inline description. Optional and repeatable.}
\item{\verb{@blockExamples <expr>}}{Block-level worked example configurations,
as an R expression -- evaluated when documentation is generated -- that
yields a list of complete configurations (each a named list keyed by
argument). Optional; supersedes the per-argument \verb{[example]} assembly.}
\item{\verb{@blockCtor <name>}}{Constructor name override. Optional: the
documented object otherwise supplies the name.}
}
Multi-argument worked \code{examples} (whole-block configurations, as opposed to a
per-argument \verb{[example]}) remain out of the tags' scope; a block needing
those registers via \code{\link[=register_block]{register_block()}} directly.
}

