Update

pnmixerlib/errors/index.html

@@ -48,7 +48,7 @@
                    <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                        [<span class='inner'>&#x2212;</span>]
                    </a>
-               </span><a class='srclink' href='../../src/pnmixerlib/errors.rs.html#1-116' title='goto source code'>[src]</a></span></h1>
+               </span><a class='srclink' href='../../src/pnmixerlib/errors.rs.html#1-109' title='goto source code'>[src]</a></span></h1>
 <h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
 <table>
                        <tr class=' module-item'>

pnmixerlib/index.html

@@ -48,8 +48,36 @@
                    <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                        [<span class='inner'>&#x2212;</span>]
                    </a>
-               </span><a class='srclink' href='../src/pnmixerlib/lib.rs.html#1-61' title='goto source code'>[src]</a></span></h1>
+               </span><a class='srclink' href='../src/pnmixerlib/lib.rs.html#1-90' title='goto source code'>[src]</a></span></h1>
-<h2 id='reexports' class='section-header'><a href="#reexports">Reexports</a></h2>
+<div class='docblock'><p>PNMixer-rs is a mixer for the system tray.</p>
+
+<h1 id='design-overview' class='section-header'><a href='#design-overview'>Design Overview</a></h1>
+<p>The lowest level part of the code is the sound backend. Only Alsa is supported
+at the moment, but more backends may be added in the future.</p>
+
+<p>The backend is hidden behind a frontend, defined in <code>audio.rs</code>. Only <code>audio.rs</code>
+deals with audio backends. This means that the whole of the code is blissfully
+ignorant of the audio backend in use.</p>
+
+<p><code>audio.rs</code> is also in charge of emitting signals whenever a change happens.
+This means that PNMixer-rs design is quite signal-oriented, so to say.</p>
+
+<p>The ui code is nothing fancy. Each ui element...</p>
+
+<ul>
+<li>is defined in a single file</li>
+<li>strives to be standalone</li>
+<li>accesses the sound system with function calls</li>
+<li>listens to signals from the audio subsystem to update its appearance</li>
+</ul>
+
+<p>There&#39;s something you should keep in mind. Audio on a computer is a shared
+resource. PNMixer-rs isn&#39;t the only one that can change it. At any moment the
+audio volume may be modified by someone else, and we must update the ui
+accordingly. So listening to changes from the audio subsystem (and therefore
+having a signal-oriented design) is the most obvious solution to solve that
+problem.</p>
+</div><h2 id='reexports' class='section-header'><a href="#reexports">Reexports</a></h2>
 <table><tr><td><code>pub extern crate <a class="mod" href="../flexi_logger/index.html" title="mod flexi_logger">flexi_logger</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../log/index.html" title="mod log">log</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../error_chain/index.html" title="mod error_chain">error_chain</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../serde_derive/index.html" title="mod serde_derive">serde_derive</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../toml/index.html" title="mod toml">toml</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../serde/index.html" title="mod serde">serde</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../alsa/index.html" title="mod alsa">alsa</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../alsa_sys/index.html" title="mod alsa_sys">alsa_sys</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../ffi/index.html" title="mod ffi">ffi</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gdk/index.html" title="mod gdk">gdk</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gdk_pixbuf/index.html" title="mod gdk_pixbuf">gdk_pixbuf</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gdk_pixbuf_sys/index.html" title="mod gdk_pixbuf_sys">gdk_pixbuf_sys</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gdk_sys/index.html" title="mod gdk_sys">gdk_sys</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gio/index.html" title="mod gio">gio</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../glib/index.html" title="mod glib">glib</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../glib_sys/index.html" title="mod glib_sys">glib_sys</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gobject_sys/index.html" title="mod gobject_sys">gobject_sys</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gtk/index.html" title="mod gtk">gtk</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../gtk_sys/index.html" title="mod gtk_sys">gtk_sys</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../libc/index.html" title="mod libc">libc</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../png/index.html" title="mod png">png</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../which/index.html" title="mod which">which</a>;</code></td></tr><tr><td><code>pub extern crate <a class="mod" href="../xdg/index.html" title="mod xdg">xdg</a>;</code></td></tr></table><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
 <table>
                        <tr class=' module-item'>
@@ -178,35 +206,32 @@ in the binary and decodes it.</p>
                            <td><a class="macro" href="macro.try_e.html"
                                   title='macro pnmixerlib::try_e'>try_e</a></td>
                            <td class='docblock-short'>
-                                
+                                <p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
-                           </td>
+otherwise print an error and exit the program.</p>
-                       </tr>
-                       <tr class=' module-item'>
-                           <td><a class="macro" href="macro.try_er.html"
-                                  title='macro pnmixerlib::try_er'>try_er</a></td>
-                           <td class='docblock-short'>
-                                
                            </td>
                        </tr>
                        <tr class=' module-item'>
                            <td><a class="macro" href="macro.try_r.html"
                                   title='macro pnmixerlib::try_r'>try_r</a></td>
                            <td class='docblock-short'>
-                                
+                                <p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
+otherwise return from the function with the given value.</p>
                            </td>
                        </tr>
                        <tr class=' module-item'>
                            <td><a class="macro" href="macro.try_w.html"
                                   title='macro pnmixerlib::try_w'>try_w</a></td>
                            <td class='docblock-short'>
-                                
+                                <p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
+otherwise print a warning and <code>return ()</code> from the function.</p>
                            </td>
                        </tr>
                        <tr class=' module-item'>
                            <td><a class="macro" href="macro.try_wr.html"
                                   title='macro pnmixerlib::try_wr'>try_wr</a></td>
                            <td class='docblock-short'>
-                                
+                                <p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
+otherwise print a warning and return from the function with the given value.</p>
                            </td>
                        </tr></table></section>
     <section id='search' class="content hidden"></section>

pnmixerlib/macro.try_e.html

@@ -48,14 +48,16 @@
                    <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                        [<span class='inner'>&#x2212;</span>]
                    </a>
-               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#78-88' title='goto source code'>[src]</a></span></h1>
+               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#85-109' title='goto source code'>[src]</a></span></h1>
 <pre class="rust macro">
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_e</span> {
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> { ... };
-    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">arg</span>:<span class="ident">tt</span>)<span class="op">+</span>) <span class="op">=&gt;</span> { ... };
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> { ... };
+    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">arg</span>:<span class="ident">tt</span>)<span class="op">+</span>) <span class="op">=&gt;</span> { ... };
 }</pre>
-</section>
+<div class='docblock'><p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
+otherwise print an error and exit the program.</p>
+</div></section>
     <section id='search' class="content hidden"></section>
 
     <section class="footer"></section>

pnmixerlib/macro.try_r.html

@@ -48,12 +48,14 @@
                    <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                        [<span class='inner'>&#x2212;</span>]
                    </a>
-               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#66-73' title='goto source code'>[src]</a></span></h1>
+               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#72-79' title='goto source code'>[src]</a></span></h1>
 <pre class="rust macro">
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_r</span> {
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> { ... };
 }</pre>
-</section>
+<div class='docblock'><p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
+otherwise return from the function with the given value.</p>
+</div></section>
     <section id='search' class="content hidden"></section>
 
     <section class="footer"></section>

pnmixerlib/macro.try_w.html

@@ -48,14 +48,16 @@
                    <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                        [<span class='inner'>&#x2212;</span>]
                    </a>
-               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#24-34' title='goto source code'>[src]</a></span></h1>
+               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#26-36' title='goto source code'>[src]</a></span></h1>
 <pre class="rust macro">
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_w</span> {
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> { ... };
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">arg</span>:<span class="ident">tt</span>)<span class="op">+</span>) <span class="op">=&gt;</span> { ... };
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> { ... };
 }</pre>
-</section>
+<div class='docblock'><p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
+otherwise print a warning and <code>return ()</code> from the function.</p>
+</div></section>
     <section id='search' class="content hidden"></section>
 
     <section class="footer"></section>

pnmixerlib/macro.try_wr.html

@@ -48,14 +48,16 @@
                    <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                        [<span class='inner'>&#x2212;</span>]
                    </a>
-               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#38-62' title='goto source code'>[src]</a></span></h1>
+               </span><a class='srclink' href='../src/pnmixerlib/errors.rs.html#42-66' title='goto source code'>[src]</a></span></h1>
 <pre class="rust macro">
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_wr</span> {
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> { ... };
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> { ... };
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">arg</span>:<span class="ident">tt</span>)<span class="op">+</span>) <span class="op">=&gt;</span> { ... };
 }</pre>
-</section>
+<div class='docblock'><p>Try to unwrap a <code>Result&lt;T, E&gt;</code>. If there is a value <code>T</code>, yield it,
+otherwise print a warning and return from the function with the given value.</p>
+</div></section>
     <section id='search' class="content hidden"></section>
 
     <section class="footer"></section>

pnmixerlib/sidebar-items.js

@@ -1 +1 @@
-initSidebarItems({"macro":[["create_builder_item",""],["pixbuf_new_from_png","Create a pixbuf from the given PNG file. Includes the file as bytes in the binary and decodes it."],["try_e",""],["try_er",""],["try_r",""],["try_w",""],["try_wr",""]],"mod":[["alsa_card","Alsa audio subsystem."],["app_state","Global application state."],["audio","High-level audio subsystem."],["errors",""],["glade_helpers",""],["prefs","The preferences subsystem."],["support_alsa","Alsa audio helper functions."],["support_audio","Helper functions of the audio subsystem."],["support_cmd","Helper functions for invoking system commands."],["support_ui","Helper functions for the UI, mostly pixbuf functions."],["ui_entry","Global GUI state."],["ui_popup_menu","The popup menu subsystem when the user right-clicks on the tray icon."],["ui_popup_window","The popup window subsystem when the user left-clicks on the tray icon."],["ui_prefs_dialog","The preferences window subsystem, when the user clicks the \"Preferences\" menu item on the popup menu."],["ui_tray_icon","The tray icon subsystem."]]});
+initSidebarItems({"macro":[["create_builder_item",""],["pixbuf_new_from_png","Create a pixbuf from the given PNG file. Includes the file as bytes in the binary and decodes it."],["try_e","Try to unwrap a `Result<T, E>`. If there is a value `T`, yield it, otherwise print an error and exit the program."],["try_r","Try to unwrap a `Result<T, E>`. If there is a value `T`, yield it, otherwise return from the function with the given value."],["try_w","Try to unwrap a `Result<T, E>`. If there is a value `T`, yield it, otherwise print a warning and `return ()` from the function."],["try_wr","Try to unwrap a `Result<T, E>`. If there is a value `T`, yield it, otherwise print a warning and return from the function with the given value."]],"mod":[["alsa_card","Alsa audio subsystem."],["app_state","Global application state."],["audio","High-level audio subsystem."],["errors",""],["glade_helpers",""],["prefs","The preferences subsystem."],["support_alsa","Alsa audio helper functions."],["support_audio","Helper functions of the audio subsystem."],["support_cmd","Helper functions for invoking system commands."],["support_ui","Helper functions for the UI, mostly pixbuf functions."],["ui_entry","Global GUI state."],["ui_popup_menu","The popup menu subsystem when the user right-clicks on the tray icon."],["ui_popup_window","The popup window subsystem when the user left-clicks on the tray icon."],["ui_prefs_dialog","The preferences window subsystem, when the user clicks the \"Preferences\" menu item on the popup menu."],["ui_tray_icon","The tray icon subsystem."]]});

src/pnmixerlib/errors.rs.html

@@ -152,13 +152,6 @@
 <span id="107">107</span>
 <span id="108">108</span>
 <span id="109">109</span>
-<span id="110">110</span>
-<span id="111">111</span>
-<span id="112">112</span>
-<span id="113">113</span>
-<span id="114">114</span>
-<span id="115">115</span>
-<span id="116">116</span>
 </pre><pre class="rust ">
 <span class="attribute">#<span class="op">!</span>[<span class="ident">allow</span>(<span class="ident">missing_docs</span>)]</span>
 
@@ -183,6 +176,8 @@
 
 
 <span class="attribute">#[<span class="ident">macro_export</span>]</span>
+<span class="doccomment">/// Try to unwrap a `Result&lt;T, E&gt;`. If there is a value `T`, yield it,</span>
+<span class="doccomment">/// otherwise print a warning and `return ()` from the function.</span>
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_w</span> {
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> {
         <span class="macro">try_wr</span><span class="macro">!</span>(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>, ())
@@ -197,6 +192,8 @@
 
 
 <span class="attribute">#[<span class="ident">macro_export</span>]</span>
+<span class="doccomment">/// Try to unwrap a `Result&lt;T, E&gt;`. If there is a value `T`, yield it,</span>
+<span class="doccomment">/// otherwise print a warning and return from the function with the given value.</span>
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_wr</span> {
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Ok</span>(<span class="ident">val</span>) <span class="op">=&gt;</span> <span class="ident">val</span>,
@@ -225,6 +222,8 @@
 
 
 <span class="attribute">#[<span class="ident">macro_export</span>]</span>
+<span class="doccomment">/// Try to unwrap a `Result&lt;T, E&gt;`. If there is a value `T`, yield it,</span>
+<span class="doccomment">/// otherwise return from the function with the given value.</span>
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_r</span> {
     (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Ok</span>(<span class="ident">val</span>) <span class="op">=&gt;</span> <span class="ident">val</span>,
@@ -235,31 +234,18 @@
 }
 
 
-
 <span class="attribute">#[<span class="ident">macro_export</span>]</span>
+<span class="doccomment">/// Try to unwrap a `Result&lt;T, E&gt;`. If there is a value `T`, yield it,</span>
+<span class="doccomment">/// otherwise print an error and exit the program.</span>
 <span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_e</span> {
-    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> {
+    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
-        <span class="macro">try_er</span><span class="macro">!</span>(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>, ())
-    };
-    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">arg</span>:<span class="ident">tt</span>)<span class="op">+</span>) <span class="op">=&gt;</span> {
-        <span class="macro">try_er</span><span class="macro">!</span>(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>, (), <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>, $(<span class="ident">arg</span>)<span class="op">+</span>)
-    };
-    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> {
-        <span class="macro">try_er</span><span class="macro">!</span>(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>, (), <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>)
-    }
-}
-
-
-<span class="attribute">#[<span class="ident">macro_export</span>]</span>
-<span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">try_er</span> {
-    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Ok</span>(<span class="ident">val</span>) <span class="op">=&gt;</span> <span class="ident">val</span>,
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Err</span>(<span class="ident">err</span>) <span class="op">=&gt;</span> {
             <span class="macro">error</span><span class="macro">!</span>(<span class="string">&quot;{:?}&quot;</span>, <span class="ident">err</span>);
             ::<span class="ident">std</span>::<span class="ident">process</span>::<span class="ident">exit</span>(<span class="number">1</span>);
         },
     });
-    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
+    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Ok</span>(<span class="ident">val</span>) <span class="op">=&gt;</span> <span class="ident">val</span>,
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Err</span>(<span class="ident">err</span>) <span class="op">=&gt;</span> {
             <span class="macro">error</span><span class="macro">!</span>(<span class="string">&quot;Original error: {:?}&quot;</span>, <span class="ident">err</span>);
@@ -267,7 +253,7 @@
             <span class="ident">std</span>::<span class="ident">process</span>::<span class="ident">exit</span>(<span class="number">1</span>);
         },
     });
-    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">ret</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">arg</span>:<span class="ident">tt</span>)<span class="op">+</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
+    (<span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span>:<span class="ident">expr</span>, <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fmt</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">arg</span>:<span class="ident">tt</span>)<span class="op">+</span>) <span class="op">=&gt;</span> (<span class="kw">match</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">expr</span> {
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Ok</span>(<span class="ident">val</span>) <span class="op">=&gt;</span> <span class="ident">val</span>,
         ::<span class="ident">std</span>::<span class="ident">result</span>::<span class="prelude-ty">Result</span>::<span class="prelude-val">Err</span>(<span class="ident">err</span>) <span class="op">=&gt;</span> {
             <span class="macro">error</span><span class="macro">!</span>(<span class="string">&quot;Original error: {:?}&quot;</span>, <span class="ident">err</span>);

src/pnmixerlib/lib.rs.html

@@ -104,7 +104,65 @@
 <span id="59">59</span>
 <span id="60">60</span>
 <span id="61">61</span>
+<span id="62">62</span>
+<span id="63">63</span>
+<span id="64">64</span>
+<span id="65">65</span>
+<span id="66">66</span>
+<span id="67">67</span>
+<span id="68">68</span>
+<span id="69">69</span>
+<span id="70">70</span>
+<span id="71">71</span>
+<span id="72">72</span>
+<span id="73">73</span>
+<span id="74">74</span>
+<span id="75">75</span>
+<span id="76">76</span>
+<span id="77">77</span>
+<span id="78">78</span>
+<span id="79">79</span>
+<span id="80">80</span>
+<span id="81">81</span>
+<span id="82">82</span>
+<span id="83">83</span>
+<span id="84">84</span>
+<span id="85">85</span>
+<span id="86">86</span>
+<span id="87">87</span>
+<span id="88">88</span>
+<span id="89">89</span>
+<span id="90">90</span>
 </pre><pre class="rust ">
+<span class="doccomment">//! PNMixer-rs is a mixer for the system tray.</span>
+<span class="doccomment">//!</span>
+<span class="doccomment">//! # Design Overview</span>
+<span class="doccomment">//!</span>
+<span class="doccomment">//! The lowest level part of the code is the sound backend. Only Alsa is supported</span>
+<span class="doccomment">//! at the moment, but more backends may be added in the future.</span>
+<span class="doccomment">//!</span>
+<span class="doccomment">//! The backend is hidden behind a frontend, defined in `audio.rs`. Only `audio.rs`</span>
+<span class="doccomment">//! deals with audio backends. This means that the whole of the code is blissfully</span>
+<span class="doccomment">//! ignorant of the audio backend in use.</span>
+<span class="doccomment">//!</span>
+<span class="doccomment">//! `audio.rs` is also in charge of emitting signals whenever a change happens.</span>
+<span class="doccomment">//! This means that PNMixer-rs design is quite signal-oriented, so to say.</span>
+<span class="doccomment">//!</span>
+<span class="doccomment">//! The ui code is nothing fancy. Each ui element...</span>
+<span class="doccomment">//!</span>
+<span class="doccomment">//! * is defined in a single file</span>
+<span class="doccomment">//! * strives to be standalone</span>
+<span class="doccomment">//! * accesses the sound system with function calls</span>
+<span class="doccomment">//! * listens to signals from the audio subsystem to update its appearance</span>
+<span class="doccomment">//!</span>
+<span class="doccomment">//! There&#39;s something you should keep in mind. Audio on a computer is a shared</span>
+<span class="doccomment">//! resource. PNMixer-rs isn&#39;t the only one that can change it. At any moment the</span>
+<span class="doccomment">//! audio volume may be modified by someone else, and we must update the ui</span>
+<span class="doccomment">//! accordingly. So listening to changes from the audio subsystem (and therefore</span>
+<span class="doccomment">//! having a signal-oriented design) is the most obvious solution to solve that</span>
+<span class="doccomment">//! problem.</span>
+
+
 <span class="attribute">#<span class="op">!</span>[<span class="ident">warn</span>(<span class="ident">missing_docs</span>)]</span>
 
 <span class="attribute">#<span class="op">!</span>[<span class="ident">feature</span>(<span class="ident">alloc_system</span>)]</span>