[pve-devel] [PATCH pve-manager 11/18] pvesr prepare-local-job: new helper

[Fabian Grünbichler]

On Tue, May 23, 2017 at 11:53:53AM +0200, Thomas Lamprecht wrote:
> 
> On 05/23/2017 11:17 AM, Wolfgang Bumiller wrote:
> > 
> > >   }
> > >   __PACKAGE__->register_method ({
> > > +    name => 'prepare_local_job',
> > > +    path => 'prepare_local_job',
> > > +    method => 'POST',
> > > +    description => "Prepare for starting a replication job. This is called on the target node before replication starts. This call is for internal use, and return a JSON object on stdout. The method first test if VM <vmid> reside on the local node. If so, stop immediately. After that the method scans all volume IDs for snapshots, and removes all replications snapshots with timestamps different than <last_sync>. It also removes any unused volumes. Returns a hash with boolean markers for all volumes with existing replication snapshots.",
> > Alternatively we could not write >500 column lines and stick with the
> > first sentence, given that the commit message is a verbatim copy of this
> > description. (Or at least split it up into multiple lines...)
> 
> Isn't there verbose_description for such cases, where description should be
> a short sentence
> and verbose_description contains more (also included in the docs then,
> AFAIK)

alternatively, introducing an "internal" flag for API paths which are
hidden from the auto-generated documentation? then we could simply put
the description into a regular comment ;)