dev-plugins: Fix code examples and header levels Fixes a few small issues with the dev-plugins doc: 1) Consistently start code examples with no indentation 2) Consistently use 2 space indents in code examples 3) Move a few sections to the correct level 4) Correct a few code examples to use java syntax 5) Fix code examples only using 3 '-' 6) Add missing closing braces to code examples Change-Id: If094cfbdc79784b3ef373fad992f237c6c7a2dbc
diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt index c3df396..b3d7a45 100644 --- a/Documentation/dev-plugins.txt +++ b/Documentation/dev-plugins.txt
@@ -74,9 +74,9 @@ manifest fields: ---- - Implementation-Title: Example plugin showing examples - Implementation-Version: 1.0 - Implementation-Vendor: Example, Inc. +Implementation-Title: Example plugin showing examples +Implementation-Version: 1.0 +Implementation-Vendor: Example, Inc. ---- === ApiType @@ -88,7 +88,7 @@ loading a plugin that needs the plugin API. ---- - Gerrit-ApiType: plugin +Gerrit-ApiType: plugin ---- === Explicit Registration @@ -103,9 +103,9 @@ `@Listen` and `@Export("")` annotations. ---- - Gerrit-Module: tld.example.project.CoreModuleClassName - Gerrit-SshModule: tld.example.project.SshModuleClassName - Gerrit-HttpModule: tld.example.project.HttpModuleClassName +Gerrit-Module: tld.example.project.CoreModuleClassName +Gerrit-SshModule: tld.example.project.SshModuleClassName +Gerrit-HttpModule: tld.example.project.HttpModuleClassName ---- === Batch runtime @@ -120,7 +120,7 @@ offline reindexing task. ---- - Gerrit-BatchModule: tld.example.project.CoreModuleClassName +Gerrit-BatchModule: tld.example.project.CoreModuleClassName ---- In this runtime, only the module designated by `Gerrit-BatchModule` is @@ -132,7 +132,7 @@ A plugin can optionally provide its own plugin name. ---- - Gerrit-PluginName: replication +Gerrit-PluginName: replication ---- This is useful for plugins that contribute plugin-owned capabilities that @@ -218,7 +218,7 @@ with no down time. ---- - Gerrit-ReloadMode: restart +Gerrit-ReloadMode: restart ---- In either mode ('restart' or 'reload') any plugin or extension can @@ -261,7 +261,7 @@ credentials and possibly verify connectivity to validate them. ---- - Gerrit-InitStep: tld.example.project.MyInitStep +Gerrit-InitStep: tld.example.project.MyInitStep ---- MyInitStep needs to follow the standard Gerrit InitStep syntax @@ -278,37 +278,37 @@ [source,java] ---- - public class MyInitStep implements InitStep { - private final String pluginName; - private final ConsoleUI ui; - private final AllProjectsConfig allProjectsConfig; +public class MyInitStep implements InitStep { + private final String pluginName; + private final ConsoleUI ui; + private final AllProjectsConfig allProjectsConfig; - @Inject - public MyInitStep(@PluginName String pluginName, ConsoleUI ui, - AllProjectsConfig allProjectsConfig) { - this.pluginName = pluginName; - this.ui = ui; - this.allProjectsConfig = allProjectsConfig; - } - - @Override - public void run() throws Exception { - } - - @Override - public void postRun() throws Exception { - ui.message("\n"); - ui.header(pluginName + " Integration"); - boolean enabled = ui.yesno(true, "By default enabled for all projects"); - Config cfg = allProjectsConfig.load().getConfig(); - if (enabled) { - cfg.setBoolean("plugin", pluginName, "enabled", enabled); - } else { - cfg.unset("plugin", pluginName, "enabled"); - } - allProjectsConfig.save(pluginName, "Initialize " + pluginName + " Integration"); - } + @Inject + public MyInitStep(@PluginName String pluginName, ConsoleUI ui, + AllProjectsConfig allProjectsConfig) { + this.pluginName = pluginName; + this.ui = ui; + this.allProjectsConfig = allProjectsConfig; } + + @Override + public void run() throws Exception { + } + + @Override + public void postRun() throws Exception { + ui.message("\n"); + ui.header(pluginName + " Integration"); + boolean enabled = ui.yesno(true, "By default enabled for all projects"); + Config cfg = allProjectsConfig.load().getConfig(); + if (enabled) { + cfg.setBoolean("plugin", pluginName, "enabled", enabled); + } else { + cfg.unset("plugin", pluginName, "enabled"); + } + allProjectsConfig.save(pluginName, "Initialize " + pluginName + " Integration"); + } +} ---- Bear in mind that the Plugin's InitStep class will be loaded but @@ -706,9 +706,12 @@ in between, leading to the final operator name. An example registration looks like this: - bind(ChangeOperatorFactory.class) - .annotatedWith(Exports.named("sample")) - .to(SampleOperator.class); +[source,java] +---- +bind(ChangeOperatorFactory.class) + .annotatedWith(Exports.named("sample")) + .to(SampleOperator.class); +---- If this is registered in the `myplugin` plugin, then the resulting operator will be named `sample_myplugin`. @@ -736,7 +739,7 @@ ---- [[search_operands]] -=== Search Operands === +== Search Operands Plugins can define new search operands to extend change searching. Plugin methods implementing search operands (returning a @@ -747,31 +750,33 @@ a module's `configure()` method in the plugin. The new operand, when used in a search would appear as: - operatorName:operandName_pluginName + `operatorName:operandName_pluginName` A sample `ChangeHasOperandFactory` class implementing, and registering, a new `has:sample_pluginName` operand is shown below: -==== - public class SampleHasOperand implements ChangeHasOperandFactory { - public static class Module extends AbstractModule { - @Override - protected void configure() { - bind(ChangeHasOperandFactory.class) - .annotatedWith(Exports.named("sample") - .to(SampleHasOperand.class); - } - } - +[source, java] +---- +public class SampleHasOperand implements ChangeHasOperandFactory { + public static class Module extends AbstractModule { @Override - public Predicate<ChangeData> create(ChangeQueryBuilder builder) - throws QueryParseException { - return new HasSamplePredicate(); + protected void configure() { + bind(ChangeHasOperandFactory.class) + .annotatedWith(Exports.named("sample") + .to(SampleHasOperand.class); } -==== + } + + @Override + public Predicate<ChangeData> create(ChangeQueryBuilder builder) + throws QueryParseException { + return new HasSamplePredicate(); + } +} +---- [[command_options]] -=== Command Options === +== Command Options Plugins can provide additional options for each of the gerrit ssh and the REST API commands by implementing the DynamicBean interface and registering @@ -800,6 +805,7 @@ logger.atSevere().log("Say Hello in the Log %s", arg); } } +} ---- === Calling Command Options === @@ -861,7 +867,7 @@ ---- [[query_attributes]] -=== Change Attributes === +== Change Attributes Plugins can provide additional attributes to be returned from the Get Change and Query Change APIs by implementing implementing the `ChangeAttributeFactory` @@ -932,13 +938,9 @@ } ---- -Example +Example: ---- - -ssh -p 29418 localhost gerrit query --myplugin-name--all "change:1" --format json - -Output: - +$ ssh -p 29418 localhost gerrit query --myplugin-name--all "change:1" --format json { "url" : "http://localhost:8080/1", "plugins" : [ @@ -951,10 +953,7 @@ ... } -curl http://localhost:8080/changes/1?myplugin-name--all - -Output: - +$ curl http://localhost:8080/changes/1?myplugin-name--all { "_number": 1, ... @@ -1096,8 +1095,8 @@ `plugin.helloworld` subsection: ---- - [plugin "helloworld"] - enabled = true +[plugin "helloworld"] + enabled = true ---- Via the `com.google.gerrit.server.config.PluginConfigFactory` class a @@ -1300,7 +1299,7 @@ Here and example of ref-updated JSON event payload with `instanceId`: [source,json] ---- +---- { "submitter": { "name": "Administrator", @@ -1317,7 +1316,7 @@ "eventCreatedOn": 1588849085, "instanceId": "instance1" } ---- +---- [[capabilities]] == Plugin Owned Capabilities @@ -1536,9 +1535,9 @@ Example config: ---- [extension-panels "CHANGE_SCREEN_BELOW_CHANGE_INFO_BLOCK"] - panel = helloworld.change_id - panel = myotherplugin - panel = myplugin.my_panel_name + panel = helloworld.change_id + panel = myotherplugin + panel = myplugin.my_panel_name ---- @@ -1763,11 +1762,11 @@ can be accessed from any REST client, i. e.: ---- - curl -X POST -H "Content-Type: application/json" \ +$ curl -X POST -H "Content-Type: application/json" \ -d '{message: "François", french: true}' \ --user joe:secret \ http://host:port/a/changes/1/revisions/1/cookbook~say-hello - "Bonjour François from change 1, patch set 1!" +"Bonjour François from change 1, patch set 1!" ---- A special case is to bind an endpoint without a view name. This is @@ -1864,7 +1863,6 @@ [source,java] ---- public class MyTopMenuExtension implements TopMenu { - @Override public List<MenuEntry> getEntries() { return Lists.newArrayList( @@ -1881,7 +1879,6 @@ [source,java] ---- public class MyTopMenuExtension implements TopMenu { - @Override public List<MenuEntry> getEntries() { return Lists.newArrayList( @@ -1899,17 +1896,17 @@ specific requests and add an menu item for this: [source,java] ---- - new MenuItem("My Screen", "/plugins/myplugin/project/${projectName}"); ---- +---- +new MenuItem("My Screen", "/plugins/myplugin/project/${projectName}"); +---- This also enables plugins to provide menu items for project aware screens: [source,java] ---- - new MenuItem("My Screen", "/x/my-screen/for/${projectName}"); ---- +---- +new MenuItem("My Screen", "/x/my-screen/for/${projectName}"); +---- If no Guice modules are declared in the manifest, the top menu extension may use auto-registration by providing an `@Listen` annotation: @@ -2123,7 +2120,6 @@ bind(AccountExternalIdCreator.class) .annotatedWith(UniqueAnnotations.create()) .to(MyExternalIdCreator.class); -} ---- [[download-commands]] @@ -2190,7 +2186,6 @@ @Listen public class MyWeblinkPlugin implements PatchSetWebLink { - private String name = "MyLink"; private String placeHolderUrlProjectCommit = "http://my.tool.com/project=%s/commit=%s"; private String imageUrl = "http://placehold.it/16x16.gif"; @@ -2270,7 +2265,6 @@ import com.google.inject.servlet.ServletModule; public class HttpModule extends ServletModule { - @Override protected void configureServlets() { serveRegex(URL_REGEX).with(LfsApiServlet.class); @@ -2281,7 +2275,7 @@ import org.eclipse.jgit.lfs.server.s3.S3Repository; public class S3LargeFileRepository extends S3Repository { -... + ... } ---- @@ -2331,8 +2325,8 @@ file. For example: ---- - [plugin "my-plugin"] - metricsPrefix = my-metrics +[plugin "my-plugin"] + metricsPrefix = my-metrics ---- will cause the metrics to be recorded under `my-metrics/${metric-name}`. @@ -2355,6 +2349,7 @@ implementation, e.g. one that supports cluster setup with multiple primary Gerrit nodes handling write operations. +[source,java] ---- DynamicItem.bind(binder(), AccountPatchReviewStore.class) .to(MultiMasterAccountPatchReviewStore.class); @@ -2576,6 +2571,8 @@ @Override public String intercept(String in) { return pluginName + " mycommand"; + } +} ---- [[ssh-command-execution-interception]] @@ -2609,7 +2606,8 @@ And then declare it in your SSH module: [source, java] ---- - DynamicSet.bind(binder(), SshExecuteCommandInterceptor.class).to(SshExecuteCommandInterceptorImpl.class); +DynamicSet.bind(binder(), SshExecuteCommandInterceptor.class) + .to(SshExecuteCommandInterceptorImpl.class); ---- [[pre-submit-evaluator]]