From bda7e9ad2180c87de58f3900c16e850ac763a69c Mon Sep 17 00:00:00 2001
From: Victor Gridnevsky <vic.6r1d@gmail.com>
Date: Mon, 8 Mar 2021 05:02:27 +0300
Subject: [PATCH] Updates docs

---
 doc/index.rst |  1 +
 doc/plans.rst | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 doc/plans.rst

diff --git a/doc/index.rst b/doc/index.rst
index 678ffb2..6061b15 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -23,6 +23,7 @@ Contents
    errors
    feature_translation
    rewrite_changes
+   plans
 
 Indices and tables
 ==================
diff --git a/doc/plans.rst b/doc/plans.rst
new file mode 100644
index 0000000..5ad1efb
--- /dev/null
+++ b/doc/plans.rst
@@ -0,0 +1,81 @@
+Plans
+=====
+
+There are things I want to change, but issues are already full with random stuff I'll need to track.
+This document exists to handle things gradually, not create issues when I solve other issues.
+(It seems I will always create more than I solve.)
+
+**P.S.**: this doesn't seem like a good way to continue, because now there's a "clutter 1" and "clutter 2", but I'll let time to show how it goes.
+
+------------
+
+Terminology
+-----------
+
+Terms I want to change
+^^^^^^^^^^^^^^^^^^^^^^
+
+Check if "port_config->virtual_seq_name" is a term that makes sense, rename if it doesn't.
+
+Callback and queues
+-------------------
+
+Error queue in callback examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When I finished a callback example, closing issue #14, I noticed there's still a queue for errors that happened in input thread.
+I am thinking about a different method of error propagation. There are also disconnections, which aren't exactly errors.
+I think I can replace error queue with callback calls easily.
+In which thread the callback runs, though?
+I also feel like I'll have to redesign "serr" function to work well with a new "error" or "status callback" mechanism.
+
+Implementation details
+----------------------
+
+Port capabilities while retrieving a port name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+RtMIDI has two Alsa `getPortName` methods, I have one `get_full_port_name` function.
+
+Port capabilities in RtMIDI might've been inverted, and I think that I have inverted them back, properly. I am probably wrong, but I debugged it and it works for some reason.
+
+.. code:: c
+
+  if (in) port_mode = SND_SEQ_PORT_CAP_WRITE | SND_SEQ_PORT_CAP_SUBS_WRITE;
+  else    port_mode = SND_SEQ_PORT_CAP_READ | SND_SEQ_PORT_CAP_SUBS_READ;
+
+"SND_SEQ_PORT_CAP_WRITE" is defined as "writable to this port", too.
+
+Does it mean RtMIDI's "getPortName" did not work in a recent release, or am I wrong somewhere?..
+
+Architectural changes
+---------------------
+
+Default amount of channels?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+snd_seq_port_info_set_midi_channels accepts 16 channels. It sounds like a magic constant I'll have to fix, but I am not sure about that.
+If that is correct, a define seems enough, but moving amount of channels into a port configurator sounds even better.
+
+MIDI2 handling
+^^^^^^^^^^^^^^
+
+MIDI2 support doesn't seem to be globally implemented.
+I receive mixed news: some claim to have finished MIDI2 compatible synths, some claim MIDI2 is not supported by Windows, etc.
+For now I'll collect information and will try to prepare.
+
+* https://github.com/jackaudio/jack2/issues/535
+* https://github.com/atsushieno/cmidi2
+
+Memory management
+-----------------
+
+Check all "malloc", "calloc", "alloca" calls are cleaned up after.
+
+Self-reviews
+------------
+
+Read the header code through at least 4 times.
+I'm sure I missed something, be it apidoc or other things.
+
+Current times: 1.