improvements to docs in arrow::ipc::reader and writer

Applied a few suggestions, made `Error` sections more consistent.

arrow-ipc/src/reader.rs

@@ -1053,9 +1053,16 @@ impl<R: Read + Seek> FileReader<BufReader<R>> {
 }
 
 impl<R: Read + Seek> FileReader<R> {
-    /// Try to create a new file reader
+    /// Try to create a new file reader.
     ///
-    /// Returns errors if the file does not meet the Arrow Format footer requirements
+    /// There is no internal buffering. If buffered reads are needed you likely want to use
+    /// [`FileReader::try_new_buffered`] instead.    
+    ///
+    /// # Errors
+    ///
+    /// An ['Err'](Result::Err) may be returned if:
+    /// - the file does not meet the Arrow Format footer requirements, or
+    /// - file endianness does not match the target endianness.
     pub fn try_new(reader: R, projection: Option<Vec<usize>>) -> Result<Self, ArrowError> {
         let builder = FileReaderBuilder {
             projection,
@@ -1183,12 +1190,15 @@ impl<R: Read> StreamReader<BufReader<R>> {
 impl<R: Read> StreamReader<R> {
     /// Try to create a new stream reader.
     ///
-    /// The first message in the stream is the schema, the reader will fail if it does not
-    /// encounter a schema.
     /// To check if the reader is done, use [`is_finished(self)`](StreamReader::is_finished).
     ///
     /// There is no internal buffering. If buffered reads are needed you likely want to use
     /// [`StreamReader::try_new_buffered`] instead.
+    ///
+    /// # Errors
+    ///
+    /// An ['Err'](Result::Err) may be returned if the reader does not encounter a schema
+    /// as the first message in the stream.
     pub fn try_new(
         mut reader: R,
         projection: Option<Vec<usize>>,

arrow-ipc/src/writer.rs

@@ -855,12 +855,24 @@ impl<W: Write> FileWriter<BufWriter<W>> {
 
 impl<W: Write> FileWriter<W> {
     /// Try to create a new writer, with the schema written as part of the header
+    ///
+    /// Note the created writer is not buffered. See [`FileWriter::try_new_buffered`] for details.
+    ///
+    /// # Errors
+    ///
+    /// An ['Err'](Result::Err) may be returned if writing the header to the writer fails.
     pub fn try_new(writer: W, schema: &Schema) -> Result<Self, ArrowError> {
         let write_options = IpcWriteOptions::default();
         Self::try_new_with_options(writer, schema, write_options)
     }
 
     /// Try to create a new writer with IpcWriteOptions
+    ///
+    /// Note the created writer is not buffered. See [`FileWriter::try_new_buffered`] for details.
+    ///
+    /// # Errors
+    ///
+    /// An ['Err'](Result::Err) may be returned if writing the header to the writer fails.
     pub fn try_new_with_options(
         mut writer: W,
         schema: &Schema,
@@ -1049,12 +1061,23 @@ impl<W: Write> StreamWriter<BufWriter<W>> {
 }
 
 impl<W: Write> StreamWriter<W> {
-    /// Try to create a new writer, with the schema written as part of the header
+    /// Try to create a new writer, with the schema written as part of the header.
+    ///
+    /// Note that there is no internal buffering. See also [`StreamWriter::try_new_buffered`].
+    ///
+    /// # Errors
+    ///
+    /// An ['Err'](Result::Err) may be returned if writing the header to the writer fails.
     pub fn try_new(writer: W, schema: &Schema) -> Result<Self, ArrowError> {
         let write_options = IpcWriteOptions::default();
         Self::try_new_with_options(writer, schema, write_options)
     }
 
+    /// Try to create a new writer with [`IpcWriteOptions`].
+    ///
+    /// # Errors
+    ///
+    /// An ['Err'](Result::Err) may be returned if writing the header to the writer fails.
     pub fn try_new_with_options(
         mut writer: W,
         schema: &Schema,