Update README wording and comments on deprecated code

- Make the wording on Session[T] and similar code more straightforward
   and easy to understand for people reading pkg.go.dev.

 - Adjust the README, where it seemed more appropriate to group training
   API stuff under the "deprecated" section rather than having a
   separate section for it.

README.md

@@ -117,7 +117,7 @@ import (
 func main() {
     // This line _may_ be optional; by default the library will try to load
     // "onnxruntime.dll" on Windows, and "onnxruntime.so" on any other system.
-    // For stability, it is probably a good idea to always set this explicitly.
+    // For stability, programs should always set this explicitly.
     ort.SetSharedLibraryPath("path/to/onnxruntime.so")
 
     err := ort.InitializeEnvironment()
@@ -165,14 +165,24 @@ func main() {
 Deprecated APIs
 ---------------
 
-Older versions of this library used a typed `Session[T]` struct to keep track
-of sessions. In retrospect, associating type parameters with Sessions was
-unnecessary, and the `AdvancedSession` type, along with its associated APIs,
-was added to rectify this mistake.  For backwards compatibility, the old typed
-`Session[T]` and `DynamicSession[T]` types are still included and unlikely to
-be removed.  However, they now delegate their functionality to
-`AdvancedSession` internally.  New code should always favor using
-`AdvancedSession` directly.
+**Typed `Session[t]`:** Older versions of this library used a typed
+`Session[T]` struct to keep track of sessions. In retrospect, associating type
+parameters with Sessions was unnecessary, and the `AdvancedSession` type, along
+with its associated APIs, was added to rectify this mistake.  For backwards
+compatibility, the old typed `Session[T]` and `DynamicSession[T]` types are
+still included and unlikely to be removed.  However, they now delegate their
+functionality to `AdvancedSession` internally.  New code should always favor
+using `AdvancedSession` directly.
+
+**Onnxruntime's training API:** The training API has been deprecated as of
+onnxruntime version 1.20.  Rather than continuing to maintain wrappers for a
+deprecated API, `onnxruntime_go` has replaced the wrapper functions for the
+training API with stubs that return an error.  Users who need to continue to
+use the training API will need to use an older version.  For example the
+following versions should be compatible with training:
+
+ - Version `v1.12.1` of `onnxruntime_go`, and
+ - Version 1.19.2 of `onnxruntime`.
 
 
 Running Tests and System Compatibility for Testing
@@ -208,16 +218,3 @@ want accelerator-related tests to run, you should set the environment variable
 to the path to the onnxruntime shared library.  Afterwards, `go test -v` should
 run and pass.
 
-
-Training API Support
---------------------
-
-The training API has been deprecated as of onnxruntime version 1.20.  Rather
-than continuing to maintain wrappers for a deprecated API, `onnxruntime_go` has
-replaced the wrapper functions for the training API with stubs that return an
-error.  Users who need to continue to use the training API will need to use an
-older version.  For example the following versions should be compatible with
-training:
-
- - Version `v1.12.1` of `onnxruntime_go`, and
- - Version 1.19.2 of `onnxruntime`.

legacy_code.go

@@ -11,35 +11,23 @@ import (
 // #include "onnxruntime_wrapper.h"
 import "C"
 
-// This type of session is for ONNX networks with the same input and output
-// data types.
-//
-// NOTE: This type was written with a type parameter despite the fact that a
-// type parameter is not necessary for any of its underlying implementation,
-// which is a mistake in retrospect. It is preserved only for compatibility
-// with older code, and new users should almost certainly be using an
-// AdvancedSession instead.
-//
-// Using an AdvancedSession struct should be easier, and supports arbitrary
-// combination of input and output tensor data types as well as more options.
+// DEPRECATED: This type was written with a type parameter despite the fact
+// that a type parameter is not necessary for any of its underlying
+// implementation. It is preserved only for compatibility with older code, and
+// new users should use AdvancedSession instead. Despite the name,
+// AdvancedSession is equally simple to use and far more flexible.
 type Session[T TensorData] struct {
 	// We now delegate all of the implementation to an AdvancedSession here.
 	s *AdvancedSession
 }
 
-// Similar to Session, but does not require the specification of the input
-// and output shapes at session creation time, and allows for input and output
-// tensors to have different types. This allows for fully dynamic input to the
-// onnx model.
-//
-// NOTE: As with Session[T], new users should probably be using
-// DynamicAdvancedSession in the future.
+// DEPRECATED: See the notes on Session[T]. Use DynamicAdvancedSession instead.
 type DynamicSession[In TensorData, Out TensorData] struct {
 	s *DynamicAdvancedSession
 }
 
-// The same as NewSession, but takes a slice of bytes containing the .onnx
-// network rather than a file path.
+// DEPRECATED: See the notes on Session[T]. Use NewAdvancedSessionWithONNXData
+// instead.
 func NewSessionWithONNXData[T TensorData](onnxData []byte, inputNames,
 	outputNames []string, inputs, outputs []*Tensor[T]) (*Session[T], error) {
 	// Unfortunately, a slice of pointers that satisfy an interface don't count
@@ -63,7 +51,8 @@ func NewSessionWithONNXData[T TensorData](onnxData []byte, inputNames,
 	}, nil
 }
 
-// Similar to NewSessionWithOnnxData, but for dynamic sessions.
+// DEPRECATED: See the notes on Session[T]. Use
+// NewDynamicAdvancedSessionWithONNXData instead.
 func NewDynamicSessionWithONNXData[in TensorData, out TensorData](onnxData []byte,
 	inputNames, outputNames []string) (*DynamicSession[in, out], error) {
 	s, e := NewDynamicAdvancedSessionWithONNXData(onnxData, inputNames,
@@ -76,14 +65,7 @@ func NewDynamicSessionWithONNXData[in TensorData, out TensorData](onnxData []byt
 	}, nil
 }
 
-// Loads the ONNX network at the given path, and initializes a Session
-// instance. If this returns successfully, the caller must call Destroy() on
-// the returned session when it is no longer needed. We require the user to
-// provide the input and output tensors and names at this point, in order to
-// not need to re-allocate them every time Run() is called. The user instead
-// can just update or access the input/output tensor data after calling Run().
-// The input and output tensors MUST outlive this session, and calling
-// session.Destroy() will not destroy the input or output tensors.
+// DEPRECATED: See the notes on Session[T]. Use NewAdvancedSession instead.
 func NewSession[T TensorData](onnxFilePath string, inputNames,
 	outputNames []string, inputs, outputs []*Tensor[T]) (*Session[T], error) {
 	fileContent, e := os.ReadFile(onnxFilePath)
@@ -100,7 +82,8 @@ func NewSession[T TensorData](onnxFilePath string, inputNames,
 	return toReturn, nil
 }
 
-// Same as NewSession, but for dynamic sessions.
+// DEPRECATED: See the notes on Session[T]. Use NewDynamicAdvancedSession
+// instead.
 func NewDynamicSession[in TensorData, out TensorData](onnxFilePath string,
 	inputNames, outputNames []string) (*DynamicSession[in, out], error) {
 	fileContent, e := os.ReadFile(onnxFilePath)
@@ -129,10 +112,6 @@ func (s *Session[T]) Run() error {
 	return s.s.Run()
 }
 
-// Unlike the non-dynamic equivalents, the DynamicSession's Run() function
-// takes a list of input and output tensors rather than requiring the tensors
-// to be specified at Session creation time. It is still the caller's
-// responsibility to create and Destroy all tensors passed to this function.
 func (s *DynamicSession[in, out]) Run(inputs []*Tensor[in],
 	outputs []*Tensor[out]) error {
 	if len(inputs) != len(s.s.s.inputNames) {