editorial review

Author: renetapopova

modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc

@@ -1,19 +1,17 @@
-:description: How to write, test and deploy a user-defined aggregation function for Neo4j.
+:description: How to write, test, and deploy a user-defined aggregation function for Neo4j.
 
 :org-neo4j-procedure-UserAggregationFunction: {neo4j-javadocs-base-uri}/org/neo4j/procedure/UserAggregationFunction.html
 
 
 [[extending-neo4j-aggregation-functions]]
 = User-defined aggregation functions
 
-This describes how to write, test and deploy a user-defined aggregation function for Neo4j.
-
 _User-defined aggregation functions_ are functions that aggregate data and return a single result.
-For a comparison between user-defined procedures, functions, and aggregation functions see xref:extending-neo4j/customized-code.adoc[].
+For a comparison between user-defined procedures, functions, and aggregation functions, see xref:extending-neo4j/customized-code.adoc[].
 
 
 [[call-user-defined-aggregation-function]]
-== Call a aggregation function
+== Call an aggregation function
 
 User-defined aggregation functions are called in the same way as any other Cypher aggregation function.
 The function name must be fully qualified, so a function named `longestString` defined in the package `org.neo4j.examples` could be called using:
@@ -32,15 +30,15 @@ User-defined aggregation functions are annotated with `@UserAggregationFunction`
 The annotated function must return an instance of an aggregator class.
 An aggregator class contains one method annotated with `@UserAggregationUpdate` and one method annotated with `@UserAggregationResult`.
 The method annotated with `@UserAggregationUpdate` will be called multiple times and enables the class to aggregate data.
-When the aggregation is done the method annotated with `@UserAggregationResult` is called once and the result of the aggregation will be returned.
+When the aggregation is done, the method annotated with `@UserAggregationResult` will be called once and the result of the aggregation will be returned.
 
 See xref:extending-neo4j/values-and-types.adoc[] for details on values and types.
 
 For more details, see the Neo4j Javadocs for link:{org-neo4j-procedure-UserAggregationFunction}[`org.neo4j.procedure.UserAggregationFunction`^].
 
 [NOTE]
 ====
-The correct way to signal an error from within an aggregation function is to throw a `RuntimeException`.
+The correct way to signal an error from within an aggregation function is to throw `RuntimeException`.
 ====
 
 [source, java]
@@ -92,8 +90,8 @@ public class LongestString
 
 Tests for user-defined aggregation functions are created in the same way as those for normal user-defined functions.
 
-Below is a template for testing a user-defined aggregation function that finds the longest string.
 
+.A template for testing a user-defined aggregation function that finds the longest string.
 [source, java]
 ----
 package example;

modules/ROOT/pages/extending-neo4j/best-practices.adoc

@@ -4,15 +4,15 @@
 [[best-practices]]
 = Best practices
 
-It is also important to consider any security implications of deploying customized code.
+It is important to consider any security implications of deploying customized code.
 Refer to the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/security/securing-extensions[Operations Manual -> Securing Extensions] for details on best practices for securing user-defined procedures and functions.
 
-Since you will be running customized-built code and Neo4j in the same JVM, there are a few things you should keep in mind:
+Since you will be running custom-built code and Neo4j in the same JVM, there are a few things you should keep in mind:
 
 * Do not create or retain more objects than you strictly need to.
   Large caches in particular tend to promote more objects to the old generation, thus increasing the need for expensive full garbage collections.
 * Do not use internal Neo4j APIs.
   They are internal to Neo4j and subject to change without notice, which may break or change the behavior of your code.
 * If possible, avoid using Java object serialization or reflection in your code or in any runtime dependency that you use.
-  Otherwise, if you cannot avoid using Java object serialization and reflection, then ensure that the `-XX:+TrustFinalNonStaticFields` JVM flag is disabled in `neo4j.conf`.
+  If you cannot avoid using Java object serialization and reflection, ensure that the `-XX:+TrustFinalNonStaticFields` JVM flag is disabled in `neo4j.conf`.
 

modules/ROOT/pages/extending-neo4j/customized-code.adoc

@@ -10,14 +10,14 @@ This is the preferred means for extending Neo4j.
 Examples of use cases for procedures and functions are:
 
 * To provide access to functionality that is not available in Cypher.
-* To provide access to third party systems.
+* To provide access to third-party systems.
 * To perform graph-global operations, such as counting connected components or finding dense nodes.
 * To express a procedural operation that is difficult to express declaratively with Cypher.
 
-Procedures and functions are written in Java and compiled into _jar_ files.
-They are deployed to the database by dropping that _jar_ file into the _plugins_ directory on each standalone or clustered server.
-For the location of the _plugins_ directory, refer to link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/file-locations[Operations Manual -> File locations].
-The database must be re-started on each server to pick up new procedures and functions.
+Procedures and functions are written in Java and compiled into JAR files.
+They are deployed to the database by dropping that JAR file into the _plugins_ directory on each standalone or clustered server.
+For the location of the _plugins_ directory, refer to link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/file-locations[Operations Manual -> Default file locations].
+The database must be restarted on each server to pick up new procedures and functions.
 
 Procedures and functions can take arguments and return results.
 In addition, procedures can perform write operations on the database.
@@ -32,13 +32,13 @@ In addition, procedures can perform write operations on the database.
 | Cardinality
 
 | `Procedure`
-| For each row the procedure takes parameters and returns multiple results.
+| For each row, the procedure takes parameters and returns multiple results.
 | `+CALL abc(...)+`
 | Update allowed.
 | Changes cardinality similarly to a `MATCH` clause (0, 1, or many).
 
 | `Scalar function`
-| For each row the function takes parameters and returns a single result.
+| For each row, the function takes parameters and returns a single result.
 | `+abc(...)+`
 | Read-only.
 | Maintains cardinality, one for one.
@@ -53,9 +53,9 @@ In addition, procedures can perform write operations on the database.
 
 Neo4j also comes bundled with a number of _built-in_ procedures and functions.
 
-The available built-in procedures varies depending edition and mode, as described in link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures[Operations Manual -> Procedures].
-Running `SHOW PROCEDURES` will display the full list of procedures available in a particular database instance, including user-defined procedures.
+The available built-in procedures vary depending on edition and mode, as described in link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures[Operations Manual -> Procedures].
+Running `SHOW PROCEDURES` displays the full list of procedures available in your Neo4j DBMS, including user-defined procedures.
 
 The built-in functions are described in link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/functions[Cypher Manual -> Functions].
-Running `SHOW FUNCTIONS` will display the full list of all the functions available in a particular database instance, including user-defined functions.
+Running `SHOW FUNCTIONS` displays the full list of all the functions available in your Neo4j DBMS, including user-defined functions.
 

modules/ROOT/pages/extending-neo4j/full-text-analyzer-provider.adoc

@@ -4,15 +4,12 @@
 [[extending-neo4j-analyzer-provider]]
 = Full-text index analyzer providers
 
-This describes how to extend full-text index analyzers provided in Neo4j.
-
 Full-text indexes always have an analyzer, which describes how text is analyzed for indexing and querying.
-The analyzer breaks the text up into smaller tokens, and processes these tokens with a number of filters.
-These filters can do many different things.
-For example, some remove stop-words, such as "the" and "is", while others transform the tokens by stemming them, or turn them into lower-case.
+The analyzer breaks the text up into smaller tokens and processes these tokens using filters.
+The filters can do different things, such as removing stop-words (e.g., _the_ and _is_), stemming the tokens, or turning them into lower-case.
 
-Which analyzer you should use depends on what you want to use the index for.
-For example, if the text being indexed belong to a special domain, such as email addresses, you would want an analyzer specific to that domain.
+Which analyzer to use, depends on what you want to use the index for.
+For example, if the text being indexed belongs to a special domain, such as email addresses, you would want an analyzer specific to that domain.
 Or if the text is always in a particular language, such as Russian, you could use an analyzer specific to that language.
 
 Neo4j comes with a number of built-in analyzers.
@@ -24,7 +21,7 @@ This default can be changed with the `dbms.index.fulltext.default_analyzer` sett
 This setting only takes effect when a full-text index is created.
 Once a full-text index has been created, it remembers the analyzer in its index-specific settings.
 
-It is possible to extend the available analyzers in Neo4j, by implementing an `AnalyzerProvider`.
+It is possible to extend the available analyzers in Neo4j by implementing `AnalyzerProvider`.
 The `AnalyzerProvider` acts as a factory, which builds the concrete Lucene `Analyzer` instance used by the index.
 The following example creates a customized analyzer:
 
@@ -61,21 +58,21 @@ public class CustomAnalyzerProvider extends AnalyzerProvider // <1>
 <1> The `CustomAnalyzerProvider` class must be `public`, and it must extend the `org.neo4j.graphdb.schema.AnalyzerProvider` class.
 <2> The `CustomAnalyzerProvider` class must additionally have a `public` constructor that takes no arguments.
     Without this constructor, the new analyzer provider will not be loaded by Neo4j.
-    There will be no warnings logged when an analyzer provider is ignored for this reason, so take care.
+    There will be no warnings logged when an analyzer provider is ignored because of this reason, so take care.
 <3> The constructor must then call its super-constructor, and give the name of the `custom-analyzer` provider as an argument.
-    This is the name that will be used to refer to this analyzer provider, when configuring indexes.
+    This is the name that will be used to refer to this analyzer provider when configuring indexes.
 <4> Lastly, the `createAnalyzer` method must be implemented.
     This method creates and returns the concrete `Analyzer` instance, that the indexes will use.
-    If this method returns `null` or throws an exception, then the index will be marked as FAILED.
-<5> In this example, we are creating instances of Lucene's `CustomAnalyzer`.
-    We can, however, create and return anything that extends the `org.apache.lucene.analysis.Analyzer` class.
+    If this method returns `null` or throws an exception, the index will be marked as FAILED.
+<5> This example creates instances of Lucene's `CustomAnalyzer`.
+    You can, however, create and return anything that extends the `org.apache.lucene.analysis.Analyzer` class.
 
 Follow the guide in xref:extending-neo4j/project-setup.adoc[], to learn how to package the customized `AnalyzerProvider` in a JAR file that can be integrated into Neo4j.
 
 The analyzer providers are picked up by Neo4j via service loading.
-This means that in addition to having implemented the class above, we must also add the fully qualified class name to a service file, and put that file on the class path.
+This means that in addition to having implemented the class, you must also add the fully qualified class name to a service file, and put that file on the classpath.
 These service files are usually included in the JAR file that contains the Neo4j extensions.
-In a typical Maven project, such as the one created by the guide above, the directory structure would look like this:
+In a typical Maven project, such as the one created by xref:extending-neo4j/project-setup.adoc[], the directory structure would look like this:
 
 [source]
 ----
@@ -92,11 +89,11 @@ project/
 ----
 <1> This is the `CustomAnalyzerProvider` from our previous code example.
 <2> This is the service loader file.
-    It is a plain-text file that contains a line, with the fully qualified name, for each `AnalyzerProvider` we implement in our project.
+    It is a plain-text file that contains a line, with the fully qualified name, for each `AnalyzerProvider` implemented in our project.
     In this case, it contains a single line: `my_package.CustomAnalyzerProvider`.
 
 
-In order for the `META-INF/services` resources to be handled correctly by the `maven-shade-plugin`, it may be necessary to include a service resource transformation to the plug-in configuration.
+For the `META-INF/services` resources to be handled correctly by the `maven-shade-plugin`, it may be necessary to include a service resource transformation to the plug-in configuration.
 This is an example of what that may look like:
 
 [source, xml]

modules/ROOT/pages/extending-neo4j/functions.adoc

@@ -6,10 +6,8 @@
 [[extending-neo4j-functions]]
 = User-defined functions
 
-This describes how to write, test and deploy a user-defined function for Neo4j.
-
-_User-defined functions_ are a simpler form of procedures that are read-only and always return a single value.
-Although they are not as powerful in capability, they are often easier to use and more efficient than procedures for many common tasks.
+_User-defined functions_ are simpler forms of procedures that return a single value and are read-only.
+Although they are less powerful in capability, they are often easier to use and more efficient than procedures for many common tasks.
 For a comparison between user-defined procedures, functions, and aggregation functions see xref:extending-neo4j/customized-code.adoc[].
 
 
@@ -29,15 +27,16 @@ RETURN org.neo4j.examples.join(collect(p.names))
 [[writing-udf]]
 == Create a function
 
-User-defined functions are created similarly to how procedures are created, but are instead annotated with `@UserFunction` and instead of returning a stream of values it returns a single value.
+User-defined functions are created similarly to how procedures are created.
+But unlike procedures, they are annotated with `@UserFunction` and return a single value instead of a stream of values.
 
 See xref:extending-neo4j/values-and-types.adoc[] for details on values and types.
 
 For more details, see the link:{org-neo4j-procedure-UserFunction}[Neo4j Javadocs for `org.neo4j.procedure.UserFunction`^].
 
 [NOTE]
 ====
-The correct way to signal an error from within a function is to throw a `RuntimeException`.
+The correct way to signal an error from within a function is to throw `RuntimeException`.
 ====
 
 [source, java]
@@ -68,8 +67,7 @@ public class Join
 
 Tests for user-defined functions are created in the same way as those for procedures.
 
-Below is a template for testing a user-defined function that joins a list of strings.
-
+.A template for testing a user-defined function that joins a list of strings.
 [source, java]
 ----
 package example;

modules/ROOT/pages/extending-neo4j/index.adoc

@@ -5,8 +5,7 @@
 = Extending Neo4j
 
 This section describes how to extend Neo4j and Cypher using procedures, functions, and plugins.
-This section introduces different methods to extend the standard Neo4j functionality.
-How to set up remote debugging is also explained.
+It introduces different methods to extend the standard Neo4j functionality and explains how to set up remote debugging.
 
 Neo4j provides the following methods to extend the standard functionality:
 
@@ -19,7 +18,7 @@ Writing extensions requires the user to be familiar with Java or other JVM progr
 //The following topics are:
 //
 //How to develop and deploy user-defined procedures and functions.
-//How to develop and deploy a customized authentication and authorization plugins.
+//How to develop and deploy customized authentication and authorization plugins.
 //How to customize the analyzer used in a full-text index.
 //How to build extensions for the Neo4j HTTP server.
 //How to configure the Neo4j server for remote debugging sessions.