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]]
