Fix docfx creation

.github/workflows/docs.yml

@@ -25,6 +25,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
+      with:
+        submodules: true
     - name: ⚙ Install prerequisites
       run: ./init.ps1 -UpgradePrerequisites
 

README.md

@@ -8,42 +8,42 @@
 
 ## Features
 
-1. [`SimplexStream`](doc/SimplexStream.md) is meant to allow two parties to communicate *one direction*.
+1. [`SimplexStream`](https://dotnet.github.io/Nerdbank.Streams/docs/SimplexStream.html) is meant to allow two parties to communicate *one direction*.
    Anything written to the stream can subsequently be read from it. You can share this `Stream`
    with any two parties (in the same AppDomain) and one can send messages to the other.
-1. [`FullDuplexStream`](doc/FullDuplexStream.md) creates a pair of bidirectional streams for
+1. [`FullDuplexStream`](https://dotnet.github.io/Nerdbank.Streams/docs/FullDuplexStream.html) creates a pair of bidirectional streams for
    in-proc two-way communication; it also creates a single bidirectional stream from two
    unidirectional streams.
-1. [`MultiplexingStream`](doc/MultiplexingStream.md) allows you to split any bidirectional
+1. [`MultiplexingStream`](https://dotnet.github.io/Nerdbank.Streams/docs/MultiplexingStream.html) allows you to split any bidirectional
    .NET Stream into many sub-streams (called channels). This allows two parties to establish
    just one transport stream (e.g. named pipe or web socket) and use it for many independent
    protocols. For example, one might set up JSON-RPC on one channel and use other channels for
    efficient binary transfers.
-1. [`AsStream()`](doc/AsStream.md) wraps a `WebSocket`, `System.IO.Pipelines.PipeReader`,
+1. [`AsStream()`](https://dotnet.github.io/Nerdbank.Streams/docs/AsStream.html) wraps a `WebSocket`, `System.IO.Pipelines.PipeReader`,
    `System.IO.Pipelines.PipeWriter`, or `System.IO.Pipelines.IDuplexPipe` with a
    `System.IO.Stream` for reading and/or writing.
-1. [`UsePipe()`](doc/UsePipe.md) enables reading from
+1. [`UsePipe()`](https://dotnet.github.io/Nerdbank.Streams/docs/UsePipe.html) enables reading from
    and writing to a `Stream` or `WebSocket` using the `PipeReader` and `PipeWriter` APIs.
-1. [`Stream.ReadSlice(long)`](doc/ReadSlice.md) creates a sub-stream that ends after
+1. [`Stream.ReadSlice(long)`](https://dotnet.github.io/Nerdbank.Streams/docs/ReadSlice.html) creates a sub-stream that ends after
    a given number of bytes.
-1. [`PipeReader.ReadSlice(long)`](doc/ReadSlice.md) creates a sub-`PipeReader` that ends after
+1. [`PipeReader.ReadSlice(long)`](https://dotnet.github.io/Nerdbank.Streams/docs/ReadSlice.html) creates a sub-`PipeReader` that ends after
    a given number of bytes.
-1. [`MonitoringStream`](doc/MonitoringStream.md) wraps another Stream and raises events for
+1. [`MonitoringStream`](https://dotnet.github.io/Nerdbank.Streams/docs/MonitoringStream.html) wraps another Stream and raises events for
    all I/O calls so you can monitor and/or trace the data as it goes by.
-1. [`WriteSubstream` and `ReadSubstream`](doc/Substream.md) allow you to serialize data of
+1. [`WriteSubstream` and `ReadSubstream`](https://dotnet.github.io/Nerdbank.Streams/docs/Substream.html) allow you to serialize data of
    an unknown length as part of a larger stream, and later deserialize it such in reading the
    substream, you cannot read more bytes than were written to it.
-1. [`Sequence<T>`](doc/Sequence.md) is a builder for `ReadOnlySequence<T>`.
-1. [`PrefixingBufferWriter<T>`](doc/PrefixingBufferWriter.md) wraps another `IBufferWriter<T>`
+1. [`Sequence<T>`](https://dotnet.github.io/Nerdbank.Streams/docs/Sequence.html) is a builder for `ReadOnlySequence<T>`.
+1. [`PrefixingBufferWriter<T>`](https://dotnet.github.io/Nerdbank.Streams/docs/PrefixingBufferWriter.html) wraps another `IBufferWriter<T>`
    to allow for prefixing some header to the next written buffer, which may be arbitrarily long.
-1. [`BufferTextWriter`](doc/BufferTextWriter.md) is a `TextWriter`-derived type that can
+1. [`BufferTextWriter`](https://dotnet.github.io/Nerdbank.Streams/docs/BufferTextWriter.html) is a `TextWriter`-derived type that can
    write directly to any `IBufferWriter<byte>`, making it more reusable than `StreamWriter`
    and thus allows for alloc-free writing across many writers.
-1. [`SequenceTextReader`](doc/SequenceTextReader.md) is a `TextReader`-derived type that can
+1. [`SequenceTextReader`](https://dotnet.github.io/Nerdbank.Streams/docs/SequenceTextReader.html) is a `TextReader`-derived type that can
    read directly from any `ReadOnlySequence<byte>`, making it more reusable than `StreamReader`
    and thus allows for alloc-free reading across many sequences.
-1. [`DuplexPipe`](doc/DuplexPipe.md) is a trivial implementation of `IDuplexPipe`.
-1. [`Stream.ReadBlockAsync`](doc/ReadBlockAsync.md) guarantees to fill the supplied buffer except under certain documented conditions, instead of the regular `ReadAsync` guarantee of supplying at least 1 byte.
+1. [`DuplexPipe`](https://dotnet.github.io/Nerdbank.Streams/docs/DuplexPipe.html) is a trivial implementation of `IDuplexPipe`.
+1. [`Stream.ReadBlockAsync`](https://dotnet.github.io/Nerdbank.Streams/docs/ReadBlockAsync.html) guarantees to fill the supplied buffer except under certain documented conditions, instead of the regular `ReadAsync` guarantee of supplying at least 1 byte.
 
 ## .NET Foundation
 

doc/AsStream.md → docfx/docs/AsStream.md

@@ -1,6 +1,6 @@
 # Exposing I/O as a Stream
 
-Exposing various I/O classes as a `Stream` is trivial. Simply call the `AsStream()` extension method.
+Exposing various I/O classes as a @System.IO.Stream is trivial. Simply call the `AsStream()` extension method.
 
 ## WebSockets
 
@@ -24,10 +24,10 @@ as a .NET Stream only when message boundaries are not important to your network
 
 ## Pipes
 
-When you have a `System.IO.Pipelines.PipeReader`, a
-`System.IO.Pipelines.PipeWriter` or a `System.IO.Pipelines.IDuplexPipe`,
-you may find that you want to read/write data using `System.IO.Stream` APIs.
-The `AsStream()` extension method for each of these types will return a `Stream` object
+When you have a @System.IO.Pipelines.PipeReader, a
+@System.IO.Pipelines.PipeWriter or a @System.IO.Pipelines.IDuplexPipe,
+you may find that you want to read/write data using @System.IO.Stream APIs.
+The `AsStream()` extension method for each of these types will return a @System.IO.Stream object
 whose I/O methods will leverage the underlying pipe.
 
 The following demonstrates wrapping a `PipeReader` in a `Stream` and reading from it:
@@ -39,7 +39,7 @@ byte[] buffer = new byte[10];
 int bytesRead = await readerStream.ReadAsync(buffer, 0, buffer.Length);
 ```
 
-The following demonstrates wrapping a `PipeWriter` in a `Stream` and writing to it:
+The following demonstrates wrapping a @System.IO.Pipelines.PipeWriter in a @System.IO.Stream and writing to it:
 
 ```cs
 PipeWriter writer; // obtained some other way
@@ -48,7 +48,7 @@ byte[] buffer = { 0x1, 0x2, 0x3 };
 await writerStream.WriteAsync(buffer, 0, buffer.Length);
 ```
 
-Given an `IDuplexPipe` (which allows two-way communication over a `PipeReader`/`PipeWriter` pair),
+Given an @System.IO.Pipelines.IDuplexPipe (which allows two-way communication over a @System.IO.Pipelines.PipeReader/@System.IO.Pipelines.PipeWriter pair),
 we can wrap that as a `Stream` and use both the read and write methods on that too:
 
 ```cs
@@ -66,7 +66,7 @@ int bytesRead = await readerStream.ReadAsync(readBuffer, 0, buffer.Length);
 
 ## `ReadOnlySequence<byte>`
 
-A `ReadOnlySequence<byte>` can be exposed as a seekable, read-only `Stream`.
+A @"System.Buffers.ReadOnlySequence`1?text=ReadOnlySequence<byte>" can be exposed as a seekable, read-only @System.IO.Stream.
 This enables progressive decoding or deserializing data without allocating a single
 array for the entire sequence.
 
@@ -82,7 +82,7 @@ while ((string line = reader.ReadLine()) != null)
 
 ## `IBufferWriter<byte>`
 
-If you're building up a `ReadOnlySequence<byte>` using `Sequence<byte>`, or have another `IBufferWriter<byte>` instance,
+If you're building up a @"System.Buffers.ReadOnlySequence`1?text=ReadOnlySequence<byte>" using @"Nerdbank.Streams.Sequence`1?text=Sequence<byte>", or have another @"System.Buffers.IBufferWriter`1?text=IBufferWriter<byte>" instance,
 you can add to that sequence with `Stream` APIs using `AsStream()`:
 
 ```cs

doc/FullDuplexStream.md → docfx/docs/FullDuplexStream.md

@@ -1,12 +1,12 @@
 # Full-duplex streams
 
 This class offers functionality to:
-1. create a pair of bidirectional streams for in-proc two-way communication (`CreatePair`)
-1. create a single bidirectional stream from two unidirectional streams (`Splice`)
+1. create a pair of bidirectional streams for in-proc two-way communication (@"Nerdbank.Streams.FullDuplexStream.CreatePair*?displayProperty=nameWithType")
+1. create a single bidirectional stream from two unidirectional streams (@"Nerdbank.Streams.FullDuplexStream.Splice*?displayProperty=nameWithType")
 
 ## `CreatePair`
 
-The `FullDuplexStream.CreatePair` method provides a pair of streams, each of which can be handed to one of two parties.
+The @Nerdbank.Streams.FullDuplexStream.CreatePair*?displayProperty=nameWithType method provides a pair of streams, each of which can be handed to one of two parties.
 Each stream can be read from and written to, and these operations are used to exchange messages with the party
 holding the other stream in the pair.
 The two stream instances communicate with each other to facilitate this bidirectional message passing.
@@ -25,7 +25,7 @@ who uses their own stream. The two streams in the returned Tuple are interconnec
 
 ## `Splice`
 
-The `FullDuplexStream.Splice` method wraps a readable stream withand a writable stream
+The @Nerdbank.Streams.FullDuplexStream.Splice*?displayProperty=nameWithType method wraps a readable stream withand a writable stream
 to produce a single, bidirectional stream.
 
 ```cs

docfx/docs/features.md

@@ -1,3 +1,38 @@
 # Features
 
-TODO
+1. [`SimplexStream`](SimplexStream.md) is meant to allow two parties to communicate *one direction*.
+   Anything written to the stream can subsequently be read from it. You can share this `Stream`
+   with any two parties (in the same AppDomain) and one can send messages to the other.
+1. [`FullDuplexStream`](FullDuplexStream.md) creates a pair of bidirectional streams for
+   in-proc two-way communication; it also creates a single bidirectional stream from two
+   unidirectional streams.
+1. [`MultiplexingStream`](MultiplexingStream.md) allows you to split any bidirectional
+   .NET Stream into many sub-streams (called channels). This allows two parties to establish
+   just one transport stream (e.g. named pipe or web socket) and use it for many independent
+   protocols. For example, one might set up JSON-RPC on one channel and use other channels for
+   efficient binary transfers.
+1. [`AsStream()`](AsStream.md) wraps a `WebSocket`, `System.IO.Pipelines.PipeReader`,
+   `System.IO.Pipelines.PipeWriter`, or `System.IO.Pipelines.IDuplexPipe` with a
+   `System.IO.Stream` for reading and/or writing.
+1. [`UsePipe()`](UsePipe.md) enables reading from
+   and writing to a `Stream` or `WebSocket` using the `PipeReader` and `PipeWriter` APIs.
+1. [`Stream.ReadSlice(long)`](ReadSlice.md) creates a sub-stream that ends after
+   a given number of bytes.
+1. [`PipeReader.ReadSlice(long)`](ReadSlice.md) creates a sub-`PipeReader` that ends after
+   a given number of bytes.
+1. [`MonitoringStream`](MonitoringStream.md) wraps another Stream and raises events for
+   all I/O calls so you can monitor and/or trace the data as it goes by.
+1. [`WriteSubstream` and `ReadSubstream`](Substream.md) allow you to serialize data of
+   an unknown length as part of a larger stream, and later deserialize it such in reading the
+   substream, you cannot read more bytes than were written to it.
+1. [`Sequence<T>`](Sequence.md) is a builder for `ReadOnlySequence<T>`.
+1. [`PrefixingBufferWriter<T>`](PrefixingBufferWriter.md) wraps another `IBufferWriter<T>`
+   to allow for prefixing some header to the next written buffer, which may be arbitrarily long.
+1. [`BufferTextWriter`](BufferTextWriter.md) is a `TextWriter`-derived type that can
+   write directly to any `IBufferWriter<byte>`, making it more reusable than `StreamWriter`
+   and thus allows for alloc-free writing across many writers.
+1. [`SequenceTextReader`](SequenceTextReader.md) is a `TextReader`-derived type that can
+   read directly from any `ReadOnlySequence<byte>`, making it more reusable than `StreamReader`
+   and thus allows for alloc-free reading across many sequences.
+1. [`DuplexPipe`](DuplexPipe.md) is a trivial implementation of `IDuplexPipe`.
+1. [`Stream.ReadBlockAsync`](ReadBlockAsync.md) guarantees to fill the supplied buffer except under certain documented conditions, instead of the regular `ReadAsync` guarantee of supplying at least 1 byte.

docfx/docs/getting-started.md

@@ -9,4 +9,4 @@ Click on the badge to find its latest version and the instructions for consuming
 
 ## Usage
 
-TODO
+See the [features list](features.md) or our [~/api/Nerdbank.Streams.html]

docfx/docs/toc.yml

@@ -2,4 +2,29 @@
   href: features.md
 - name: Getting Started
   href: getting-started.md
-
+- name: Exposing I/O as a Stream
+  href: AsStream.md
+- name: TextWriter for IBufferWriter<byte>
+  href: BufferTextWriter.md
+- name: DuplexPipe
+  href: DuplexPipe.md
+- name: Full-duplex streams
+  href: FullDuplexStream.md
+- name: Monitoring Stream
+  href: MonitoringStream.md
+- name: Multiplexing Stream
+  href: MultiplexingStream.md
+- name: Prefixing buffer writer
+  href: PrefixingBufferWriter.md
+- name: Stream.ReadBlockAsync(Memory<byte>, CancellationToken)
+  href: ReadBlockAsync.md
+- name: Read sliced Stream or PipeReader
+  href: ReadSlice.md
+- name: Sequence<T>
+  href: Sequence.md
+- name: TextReader for ReadOnlySequence<byte>
+  href: SequenceTextReader.md
+- name: Simplex Stream
+  href: SimplexStream.md
+- name: Access existing I/O APIS using Pipelines
+  href: UsePipe.md

docfx/toc.yml

@@ -2,3 +2,5 @@
   href: docs/
 - name: API
   href: api/
+- name: GitHub
+  href: https://github.com/dotnet/Nerdbank.Streams

src/Nerdbank.Streams/MultiplexingStream.Channel.cs

@@ -210,7 +210,7 @@ internal Channel(MultiplexingStream multiplexingStream, QualifiedChannelId chann
             /// <summary>
             /// Gets the mechanism used for tracing activity related to this channel.
             /// </summary>
-            /// <value>A non-null value, once <see cref="ApplyChannelOptions(ChannelOptions)"/> has been called.</value>
+            /// <devvalue>A non-null value, once <see cref="ApplyChannelOptions(ChannelOptions)"/> has been called.</devvalue>
             public TraceSource? TraceSource { get; private set; }
 
             /// <inheritdoc />