Docs updates (#1432)

* Use /// <value> instead of /// <returns> for properties * misc doc updates in SshCommand * Update README
sshnet · Jul 4, 2024 · 8e8829e · 8e8829e
1 parent 56318a4
commit 8e8829e
Show file tree

Hide file tree

Showing 10 changed files with 119 additions and 131 deletions.
diff --git a/README.md b/README.md
@@ -6,36 +6,65 @@ SSH.NET is a Secure Shell (SSH-2) library for .NET, optimized for parallelism.
 [![NuGet download count](https://img.shields.io/nuget/dt/SSH.NET.svg)](https://www.nuget.org/packages/SSH.NET)
 [![Build status](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop?svg=true)](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop)
 
-## Introduction
+## Key Features
 
-This project was inspired by **Sharp.SSH** library which was ported from java and it seems like was not supported
-for quite some time. This library is a complete rewrite, without any third party dependencies, using parallelism
-to achieve the best performance possible.
+* Execution of SSH command using both synchronous and asynchronous methods
+* SFTP functionality for both synchronous and asynchronous operations
+* SCP functionality
+* Remote, dynamic and local port forwarding 
+* Interactive shell/terminal implementation
+* Authentication via publickey, password and keyboard-interactive methods, including multi-factor
+* Connection via SOCKS4, SOCKS5 or HTTP proxy
 
-## Documentation
+## How to Use
 
-Documentation is hosted at https://sshnet.github.io/SSH.NET/. Currently (4/18/2020), the documentation is very sparse.
-Fortunately, there are a large number of [tests](https://github.com/sshnet/SSH.NET/tree/develop/test/) that demonstrate usage with working code.
-If the test for the functionality you would like to see documented is not complete, then you are cordially
-invited to read the source, Luke, and highly encouraged to generate a pull request for the implementation of
-the missing test once you figure things out.  🤓
+### Run a command
 
-## Features
+```cs
+using (var client = new SshClient("sftp.foo.com", "guest", new PrivateKeyFile("path/to/my/key")))
+{
+    client.Connect();
+    using SshCommand cmd = client.RunCommand("echo 'Hello World!'");
+    Console.WriteLine(cmd.Result); // "Hello World!\n"
+}
+```
 
-* Execution of SSH command using both synchronous and asynchronous methods
-* Return command execution exit status and other information 
-* Provide SFTP functionality for both synchronous and asynchronous operations
-* Provides SCP functionality
-* Provide status report for upload and download sftp operations to allow accurate progress bar implementation 
-* Remote, dynamic and local port forwarding 
-* Shell/Terminal implementation
-* Specify key file pass phrase
-* Use multiple key files to authenticate
-* Supports publickey, password and keyboard-interactive authentication methods 
-* Supports two-factor or higher authentication
-* Supports SOCKS4, SOCKS5 and HTTP Proxy
+### Upload and list files using SFTP
+
+```cs
+using (var client = new SftpClient("sftp.foo.com", "guest", "pwd"))
+{
+    client.Connect();
+
+    using (FileStream fs = File.OpenRead(@"C:\tmp\test-file.txt"))
+    {
+        client.UploadFile(fs, "/home/guest/test-file.txt");
+    }
+
+    foreach (ISftpFile file in client.ListDirectory("/home/guest/"))
+    {
+        Console.WriteLine($"{file.FullName} {file.LastWriteTime}");
+    }
+}
+```
+
+## Main Types
+
+The main types provided by this library are:
+
+* Renci.SshNet.SshClient
+* Renci.SshNet.SftpClient
+* Renci.SshNet.ScpClient
+* Renci.SshNet.PrivateKeyFile
+* Renci.SshNet.SshCommand
+* Renci.SshNet.ShellStream
+
+## Additional Documentation
 
-## Encryption Method
+* [Further examples](https://sshnet.github.io/SSH.NET/examples.html)
+* [API browser](https://sshnet.github.io/SSH.NET/api/Renci.SshNet.html)
+
+## Encryption Methods
 
 **SSH.NET** supports the following encryption methods:
 * aes128-ctr
@@ -57,7 +86,7 @@ the missing test once you figure things out.  🤓
 * arcfour256
 * cast128-cbc
 
-## Key Exchange Method
+## Key Exchange Methods
 
 **SSH.NET** supports the following key exchange methods:
 * curve25519-sha256
@@ -131,41 +160,6 @@ Private keys can be encrypted using one of the following cipher methods:
 * .NET Standard 2.0 and 2.1
 * .NET 6 (and higher)
 
-## Usage
-
-### Multi-factor authentication
-
-Establish a SFTP connection using both password and public-key authentication:
-
-```cs
-var connectionInfo = new ConnectionInfo("sftp.foo.com",
-                                        "guest",
-                                        new PasswordAuthenticationMethod("guest", "pwd"),
-                                        new PrivateKeyAuthenticationMethod("rsa.key"));
-using (var client = new SftpClient(connectionInfo))
-{
-    client.Connect();
-}
-
-```
-
-### Verify host identify
-
-Establish a SSH connection using user name and password, and reject the connection if the fingerprint of the server does not match the expected fingerprint:
-
-```cs
-string expectedFingerPrint = "LKOy5LvmtEe17S4lyxVXqvs7uPMy+yF79MQpHeCs/Qo";
-
-using (var client = new SshClient("sftp.foo.com", "guest", "pwd"))
-{
-    client.HostKeyReceived += (sender, e) =>
-        {
-            e.CanTrust = expectedFingerPrint.Equals(e.FingerPrintSHA256);
-        };
-    client.Connect();
-}
-```
-
 ## Building the library
 
 The library has no special requirements to build, other than an up-to-date .NET SDK. See also [CONTRIBUTING.md](https://github.com/sshnet/SSH.NET/blob/develop/CONTRIBUTING.md).

diff --git a/docfx/examples.md b/docfx/examples.md
@@ -5,8 +5,6 @@ Getting Started
 
 ### Run a command
 
-Establish an SSH connection and run a command:
-
 ```cs
 using (var client = new SshClient("sftp.foo.com", "guest", new PrivateKeyFile("path/to/my/key")))
 {
@@ -16,9 +14,7 @@ using (var client = new SshClient("sftp.foo.com", "guest", new PrivateKeyFile("p
 }
 ```
 
-### Upload and list files
-
-SFTP Connection / Exchange 
+### Upload and list files using SFTP
 
 ```cs
 using (var client = new SftpClient("sftp.foo.com", "guest", "pwd"))
@@ -39,7 +35,7 @@ using (var client = new SftpClient("sftp.foo.com", "guest", "pwd"))
 
 ### Multi-factor authentication
 
-Establish an SFTP connection using both password and public-key authentication:
+Establish a connection using both password and public-key authentication:
 
 ```cs
 var connectionInfo = new ConnectionInfo("sftp.foo.com",
@@ -54,7 +50,7 @@ using (var client = new SftpClient(connectionInfo))
 
 ### Verify host identify
 
-Establish an SSH connection using user name and password, and reject the connection if the fingerprint of the server does not match the expected fingerprint:
+Establish a connection using user name and password, and reject the connection if the fingerprint of the server does not match the expected fingerprint:
 
 ```cs
 string expectedFingerPrint = "LKOy5LvmtEe17S4lyxVXqvs7uPMy+yF79MQpHeCs/Qo";

diff --git a/src/Renci.SshNet/Common/AsyncResult.cs b/src/Renci.SshNet/Common/AsyncResult.cs
@@ -92,9 +92,9 @@ internal void EndInvoke()
         /// <summary>
         /// Gets a user-defined object that qualifies or contains information about an asynchronous operation.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// A user-defined object that qualifies or contains information about an asynchronous operation.
-        /// </returns>
+        /// </value>
         public object AsyncState
         {
             get { return _asyncState; }
@@ -103,9 +103,9 @@ public object AsyncState
         /// <summary>
         /// Gets a value indicating whether the asynchronous operation completed synchronously.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// <see langword="true"/> if the asynchronous operation completed synchronously; otherwise, <see langword="false"/>.
-        /// </returns>
+        /// </value>
         public bool CompletedSynchronously
         {
             get { return _completedState == StateCompletedSynchronously; }
@@ -114,9 +114,9 @@ public bool CompletedSynchronously
         /// <summary>
         /// Gets a <see cref="WaitHandle"/> that is used to wait for an asynchronous operation to complete.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// A <see cref="WaitHandle"/> that is used to wait for an asynchronous operation to complete.
-        /// </returns>
+        /// </value>
         public WaitHandle AsyncWaitHandle
         {
             get
@@ -147,9 +147,9 @@ public WaitHandle AsyncWaitHandle
         /// <summary>
         /// Gets a value indicating whether the asynchronous operation has completed.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// <see langword="true"/> if the operation is complete; otherwise, <see langword="false"/>.
-        /// </returns>
+        /// </value>
         public bool IsCompleted
         {
             get { return _completedState != StatePending; }

diff --git a/src/Renci.SshNet/Common/ChannelInputStream.cs b/src/Renci.SshNet/Common/ChannelInputStream.cs
@@ -153,9 +153,9 @@ protected override void Dispose(bool disposing)
         /// <summary>
         /// Gets a value indicating whether the current stream supports reading.
         /// </summary>
-        /// <returns>
-        /// true if the stream supports reading; otherwise, false.
-        /// </returns>
+        /// <value>
+        /// <see langword="true"/> if the stream supports reading; otherwise, <see langword="false"/>.
+        /// </value>
         public override bool CanRead
         {
             get { return false; }
@@ -164,9 +164,9 @@ public override bool CanRead
         /// <summary>
         /// Gets a value indicating whether the current stream supports seeking.
         /// </summary>
-        /// <returns>
-        /// <c>true</c> if the stream supports seeking; otherwise, <c>false</c>.
-        /// </returns>
+        /// <value>
+        /// <see langword="true"/> if the stream supports seeking; otherwise, <see langword="false"/>.
+        /// </value>
         public override bool CanSeek
         {
             get { return false; }
@@ -175,35 +175,35 @@ public override bool CanSeek
         /// <summary>
         /// Gets a value indicating whether the current stream supports writing.
         /// </summary>
-        /// <returns>
-        /// <c>true</c> if the stream supports writing; otherwise, <c>false</c>.
-        /// </returns>
+        /// <value>
+        /// <see langword="true"/> if the stream supports writing; otherwise, <see langword="false"/>.
+        /// </value>
         public override bool CanWrite
         {
             get { return true; }
         }
 
         /// <summary>
-        /// Gets the length in bytes of the stream.
+        /// Throws <see cref="NotSupportedException"/>.
         /// </summary>
-        /// <returns>
-        /// A long value representing the length of the stream in bytes.
-        /// </returns>
-        /// <exception cref="NotSupportedException">A class derived from Stream does not support seeking.</exception>
-        /// <exception cref="ObjectDisposedException">Methods were called after the stream was closed.</exception>
+        /// <exception cref="NotSupportedException">Always.</exception>
+#pragma warning disable SA1623 // The property's documentation should begin with 'Gets or sets'
         public override long Length
+#pragma warning restore SA1623 // The property's documentation should begin with 'Gets or sets'
         {
             get { throw new NotSupportedException(); }
         }
 
         /// <summary>
-        /// Gets or sets the position within the current stream.
+        /// Gets the position within the current stream.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// The current position within the stream.
-        /// </returns>
-        /// <exception cref="NotSupportedException">The stream does not support seeking.</exception>
+        /// </value>
+        /// <exception cref="NotSupportedException">The setter is called.</exception>
+#pragma warning disable SA1623 // The property's documentation should begin with 'Gets or sets'
         public override long Position
+#pragma warning restore SA1623 // The property's documentation should begin with 'Gets or sets'
         {
             get { return _totalPosition; }
             set { throw new NotSupportedException(); }

diff --git a/src/Renci.SshNet/Common/PipeStream.cs b/src/Renci.SshNet/Common/PipeStream.cs
@@ -163,9 +163,9 @@ protected override void Dispose(bool disposing)
         /// <summary>
         /// Gets a value indicating whether the current stream supports reading.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// <see langword="true"/>.
-        /// </returns>
+        /// </value>
         /// <remarks>
         /// It is safe to read from <see cref="PipeStream"/> even after disposal.
         /// </remarks>
@@ -177,9 +177,9 @@ public override bool CanRead
         /// <summary>
         /// Gets a value indicating whether the current stream supports seeking.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// <see langword="false"/>.
-        /// </returns>
+        /// </value>
         public override bool CanSeek
         {
             get { return false; }
@@ -188,10 +188,10 @@ public override bool CanSeek
         /// <summary>
         /// Gets a value indicating whether the current stream supports writing.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// <see langword="true"/> if this stream has not been disposed and the underlying channel
         /// is still open, otherwise <see langword="false"/>.
-        /// </returns>
+        /// </value>
         /// <remarks>
         /// A value of <see langword="true"/> does not necessarily mean a write will succeed. It is possible
         /// that the stream is disposed by another thread between a call to <see cref="CanWrite"/> and the call to write.
@@ -204,7 +204,7 @@ public override bool CanWrite
         /// <summary>
         /// Gets the number of bytes currently available for reading.
         /// </summary>
-        /// <returns>A long value representing the length of the stream in bytes.</returns>
+        /// <value>A long value representing the length of the stream in bytes.</value>
         public override long Length
         {
             get
@@ -221,9 +221,9 @@ public override long Length
         /// This property always returns 0, and throws <see cref="NotSupportedException"/>
         /// when calling the setter.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// 0.
-        /// </returns>
+        /// </value>
         /// <exception cref="NotSupportedException">The setter is called.</exception>
 #pragma warning disable SA1623 // The property's documentation should begin with 'Gets or sets'
         public override long Position

diff --git a/src/Renci.SshNet/Security/Cryptography/Cipher.cs b/src/Renci.SshNet/Security/Cryptography/Cipher.cs
@@ -16,10 +16,10 @@ public abstract class Cipher
         /// <summary>
         /// Gets the size of the authentication tag for ciphers which implement Authenticated Encryption (AE).
         /// </summary>
-        /// <returns>
+        /// <value>
         /// When this <see cref="Cipher"/> implements Authenticated Encryption, the size, in bytes,
         /// of the authentication tag included in the encrypted message.
-        /// </returns>
+        /// </value>
         public virtual int TagSize { get; }
 
         /// <summary>

diff --git a/src/Renci.SshNet/Security/Cryptography/RsaKey.cs b/src/Renci.SshNet/Security/Cryptography/RsaKey.cs
@@ -108,9 +108,9 @@ public override int KeyLength
         /// <summary>
         /// Gets the digital signature implementation for this key.
         /// </summary>
-        /// <returns>
+        /// <value>
         /// An implementation of an RSA digital signature using the SHA-1 hash algorithm.
-        /// </returns>
+        /// </value>
         protected internal override DigitalSignature DigitalSignature
         {
             get