Update documentation (#229)

* Remove the await from new/connect on doc examples

* Export the conversion error types for duration and point

* Remove references to removed summary methods

* Fix type create -> crate

* Add the getting started guide to the readme

Author: knutwalker

README.md

@@ -16,23 +16,26 @@ Only the latest 5.x version is supported, following the [Neo4j Version support p
 
 ## API Documentation: [![Docs.rs][docs-badge]][docs-url]
 
+## [Getting Started](https://neo4j.com/docs/getting-started/languages-guides/community-drivers/#neo4j-rust)
+
+
 ## Example
 
 ```rust
     // concurrent queries
     let uri = "127.0.0.1:7687";
     let user = "neo4j";
     let pass = "neo";
-    let graph = Graph::new(&uri, user, pass).await.unwrap();
+    let graph = Graph::new(&uri, user, pass).unwrap();
     for _ in 1..=42 {
         let graph = graph.clone();
         tokio::spawn(async move {
             let mut result = graph.execute(
-           query("MATCH (p:Person {name: $name}) RETURN p").param("name", "Mark")
-        ).await.unwrap();
-            while let Ok(Some(row)) = result.next().await {
-            let node: Node = row.get("p").unwrap();
-            let name: String = node.get("name").unwrap();
+               query("MATCH (p:Person {name: $name}) RETURN p").param("name", "Mark")
+            ).await.unwrap();
+            while let Some(row) = result.next().await.unwrap() {
+                let node: Node = row.get("p").unwrap();
+                let name: String = node.get("name").unwrap();
                 println!("{}", name);
             }
         });

lib/src/bolt/mod.rs

@@ -18,8 +18,9 @@ pub use request::{
 };
 pub use structs::{
     Bolt, BoltRef, Date, DateDuration, DateTime, DateTimeZoneId, DateTimeZoneIdRef, Duration,
-    LegacyDateTime, LegacyDateTimeZoneId, LegacyDateTimeZoneIdRef, LocalDateTime, LocalTime, Node,
-    NodeRef, Path, PathRef, Point2D, Point3D, Relationship, RelationshipRef, Segment, Time,
+    DurationConversionError, LegacyDateTime, LegacyDateTimeZoneId, LegacyDateTimeZoneIdRef,
+    LocalDateTime, LocalTime, Node, NodeRef, Path, PathRef, Point2D, Point3D, PointConversionError,
+    Relationship, RelationshipRef, Segment, Time,
 };
 pub use summary::{Failure, Success, Summary};
 

lib/src/bolt/structs/duration.rs

@@ -41,12 +41,12 @@ impl Duration {
     }
 
     /// Returns the duration as [`std::time::Duration`], or an error if the conversion failed.
-    /// The error can be recovered using [`ConversionError::recover`].
-    pub fn as_duration(self) -> Result<StdDuration, ConversionError> {
+    /// The error can be recovered using [`DurationConversionError::recover`].
+    pub fn as_duration(self) -> Result<StdDuration, DurationConversionError> {
         if self.months == 0 {
             calculate_duration([0, self.days, self.seconds], self.nanoseconds)
         } else {
-            Err(ConversionError::EstimationRequired(DurationUnits {
+            Err(DurationConversionError::EstimationRequired(DurationUnits {
                 months: self.months,
                 days: self.days,
                 seconds: self.seconds,
@@ -56,7 +56,7 @@ impl Duration {
     }
 
     /// Returns the duration as [`std::time::Duration`], while recovering from any error.
-    /// See [`ConversionError::recover`] for more details.
+    /// See [`DurationConversionError::recover`] for more details.
     pub fn force_as_duration(self) -> StdDuration {
         self.as_duration().unwrap_or_else(|e| e.deep_recover())
     }
@@ -90,7 +90,7 @@ pub struct DurationUnits {
 }
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Error)]
-pub enum ConversionError {
+pub enum DurationConversionError {
     /// The [`Duration`] contained a month part.
     ///
     /// The length of a month varies by month-of-year.
@@ -122,28 +122,28 @@ pub enum ConversionError {
     Negative(StdDuration),
 }
 
-impl ConversionError {
+impl DurationConversionError {
     /// Try to recover from the conversion error and return a `std::time::Duration` if possible.
-    /// See [`ConversionError`] for more details.
+    /// See [`DurationConversionError`] for more details.
     ///
     /// For `EstimationRequired`, possible values after recovery are `Overflow` and `Negative`.
     /// For `Overflow`, possible values after recovery are `Negative`.
     /// Recovery will always succeed for `Negative`.
     ///
-    /// To recover through all possible values, use [`ConversionError::deep_recover`].
+    /// To recover through all possible values, use [`DurationConversionError::deep_recover`].
     pub fn recover(self) -> Result<StdDuration, Self> {
         match self {
-            ConversionError::EstimationRequired(units) => {
+            DurationConversionError::EstimationRequired(units) => {
                 calculate_duration([units.months, units.days, units.seconds], units.nanoseconds)
             }
-            ConversionError::Overflow(sign) => {
+            DurationConversionError::Overflow(sign) => {
                 if sign >= 0 {
                     Ok(StdDuration::MAX)
                 } else {
                     Err(Self::Negative(StdDuration::MAX))
                 }
             }
-            ConversionError::Negative(duration) => Ok(duration),
+            DurationConversionError::Negative(duration) => Ok(duration),
         }
     }
 
@@ -162,7 +162,7 @@ impl ConversionError {
 fn calculate_duration(
     [months, days, secs]: [i64; 3],
     nanos: i32,
-) -> Result<StdDuration, ConversionError> {
+) -> Result<StdDuration, DurationConversionError> {
     const NANOS_PER_SECOND: i32 = 1_000_000_000;
     const SECONDS_PER_DAY: u32 = 86400;
     const SECONDS_PER_MONTH: u32 = {
@@ -186,13 +186,13 @@ fn calculate_duration(
     };
 
     let sign = seconds.signum() as i32;
-    let seconds =
-        u64::try_from(seconds.unsigned_abs()).map_err(|_| ConversionError::Overflow(sign))?;
+    let seconds = u64::try_from(seconds.unsigned_abs())
+        .map_err(|_| DurationConversionError::Overflow(sign))?;
 
     let duration = StdDuration::new(seconds, subsecond);
 
     if sign < 0 {
-        Err(ConversionError::Negative(duration))
+        Err(DurationConversionError::Negative(duration))
     } else {
         Ok(duration)
     }

lib/src/bolt/structs/mod.rs

@@ -5,10 +5,10 @@ pub use self::datetime::{
     DateTime, DateTimeZoneId, DateTimeZoneIdRef, LegacyDateTime, LegacyDateTimeZoneId,
     LegacyDateTimeZoneIdRef, LocalDateTime,
 };
-pub use self::duration::Duration;
+pub use self::duration::{Duration, DurationConversionError};
 pub use self::node::{Node, NodeRef};
 pub use self::path::{Path, PathRef, Segment};
-pub use self::point::{Point2D, Point3D};
+pub use self::point::{Point2D, Point3D, PointConversionError};
 pub use self::rel::{Relationship, RelationshipRef};
 pub use self::time::{LocalTime, Time};
 

lib/src/bolt/structs/point.rs

@@ -52,7 +52,7 @@ impl Point2D {
         }
     }
 
-    pub fn as_nav(&self) -> Result<nav_types::WGS84<f64>, ConversionError> {
+    pub fn as_nav(&self) -> Result<nav_types::WGS84<f64>, PointConversionError> {
         self.to_point().as_nav()
     }
 }
@@ -110,13 +110,13 @@ impl Point3D {
         }
     }
 
-    pub fn as_nav(&self) -> Result<nav_types::WGS84<f64>, ConversionError> {
+    pub fn as_nav(&self) -> Result<nav_types::WGS84<f64>, PointConversionError> {
         self.to_point().as_nav()
     }
 }
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Error)]
-pub enum ConversionError {
+pub enum PointConversionError {
     #[error("The coordinate system is not in {0}")]
     WrongSystem(Crs),
     #[error("The point is not defined on the {0} ellipsoid.")]
@@ -225,16 +225,16 @@ pub enum Point {
 }
 
 impl Point {
-    pub fn as_nav(&self) -> Result<nav_types::WGS84<f64>, ConversionError> {
+    pub fn as_nav(&self) -> Result<nav_types::WGS84<f64>, PointConversionError> {
         match self {
             Point::Wgs842d(p) => p
                 .to_nav()
-                .ok_or(ConversionError::UndefinedPosition(Crs::Wgs842D)),
+                .ok_or(PointConversionError::UndefinedPosition(Crs::Wgs842D)),
             Point::Wgs843d(p) => p
                 .to_nav()
-                .ok_or(ConversionError::UndefinedPosition(Crs::Wgs843D)),
-            Point::Cartesian2d(_) => Err(ConversionError::WrongSystem(Crs::Wgs842D)),
-            Point::Cartesian3d(_) => Err(ConversionError::WrongSystem(Crs::Wgs843D)),
+                .ok_or(PointConversionError::UndefinedPosition(Crs::Wgs843D)),
+            Point::Cartesian2d(_) => Err(PointConversionError::WrongSystem(Crs::Wgs842D)),
+            Point::Cartesian3d(_) => Err(PointConversionError::WrongSystem(Crs::Wgs843D)),
         }
     }
 

lib/src/lib.rs

@@ -22,7 +22,7 @@
 //!    let pass = "neo";
 //!    let id = uuid::Uuid::new_v4().to_string();
 //!
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/example.rs")]
 //! }
@@ -49,7 +49,7 @@
 //!        .max_connections(10)
 //!        .build()
 //!        .unwrap();
-//!    let graph = Graph::connect(config).await.unwrap();
+//!    let graph = Graph::connect(config).unwrap();
 //!
 #![doc = include_str!("../include/configurations.rs")]
 //! }
@@ -68,7 +68,7 @@
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/nodes.rs")]
 //! }
@@ -91,7 +91,7 @@
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/transactions.rs")]
 //! }
@@ -117,7 +117,7 @@
 //!        .fetch_size(1)
 //!        .build()
 //!        .unwrap();
-//!    let graph = Graph::connect(config).await.unwrap();
+//!    let graph = Graph::connect(config).unwrap();
 //!
 #![doc = include_str!("../include/streams_within_a_transaction.rs")]
 //! }
@@ -141,7 +141,7 @@
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/result_stream.rs")]
 //! }
@@ -152,11 +152,7 @@
     feature = "unstable-result-summary",
     doc = r##"### Streaming summary
 
-To get access to the result summary after streaming a [`RowStream`], you can use the [`RowStream::next_or_summary`] method.
-Alternatively, you can use one of the [`RowStream::as_row_items`], [`RowStream::as_items`], or [`RowStream::column_to_items`]
-methods to get the result as a stream of [`RowItem`], whis an enum of either the row or the summary.
-The last option is to use one of the [`RowStream::into_stream`], [`RowStream::into_stream_as`], or [`RowStream::column_into_stream`] methods
-and after the stream is consumed, call [`RowStream::finish`] to get the summary.
+To get access to the result summary after streaming a [`RowStream`], use the [`RowStream::finish`] method.
 
 ```no_run
 use neo4rs::*;
@@ -166,7 +162,7 @@ async fn main() {
     let uri = "127.0.0.1:7687";
     let user = "neo4j";
     let pass = "neo";
-    let graph = Graph::new(uri, user, pass).await.unwrap();
+    let graph = Graph::new(uri, user, pass).unwrap();
 
 "##
 )]
@@ -188,7 +184,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/rollback_a_transaction.rs")]
 //! }
@@ -213,7 +209,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/txn_vs_graph.rs")]
 //! }
@@ -233,7 +229,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/relationships.rs")]
 //! }
@@ -250,7 +246,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/unbounded_relationships.rs")]
 //! }
@@ -272,7 +268,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 //!    let qry = "
 //!        WITH point({ x: 2.3, y: 4.5, crs: 'cartesian' }) AS p1,
@@ -295,7 +291,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/raw_bytes.rs")]
 //! }
@@ -313,7 +309,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/durations.rs")]
 //! }
@@ -333,7 +329,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/dates.rs")]
 //! }
@@ -362,7 +358,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/time_as_param.rs")]
 //! }
@@ -379,7 +375,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/parse_time_from_result.rs")]
 //! }
@@ -410,7 +406,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/datetime_as_param.rs")]
 //! }
@@ -426,7 +422,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/parse_datetime_from_result.rs")]
 //! }
@@ -445,7 +441,7 @@ async fn main() {
 //!    let uri = "127.0.0.1:7687";
 //!    let user = "neo4j";
 //!    let pass = "neo";
-//!    let graph = Graph::new(uri, user, pass).await.unwrap();
+//!    let graph = Graph::new(uri, user, pass).unwrap();
 //!
 #![doc = include_str!("../include/path.rs")]
 //! }