Be a little bit more elaborate in the comments

1 files changed, 28 insertions, 18 deletions

diff --git a/flashsupport.c b/flashsupport.c
index 3477d29..afb1959 100644
--- a/flashsupport.c
+++ b/flashsupport.c
@@ -810,7 +810,7 @@ static void context_state_cb(pa_context *c, void *userdata) {
 
     p->thread_id = pthread_self();
     p->context = c;
-    
+
     switch (pa_context_get_state(c)) {
         case PA_CONTEXT_READY:
         case PA_CONTEXT_TERMINATED:
@@ -828,7 +828,7 @@ static void context_state_cb(pa_context *c, void *userdata) {
 
 static void stream_state_cb(pa_stream *s, void *userdata) {
     struct output_data *p = userdata;
-    
+
     assert(s);
     assert(p);
 
@@ -851,22 +851,22 @@ static void stream_state_cb(pa_stream *s, void *userdata) {
 
 static void write_data(struct output_data *p) {
     size_t length;
-    
+
     assert(p);
 
     /* Wait until timing info is available before we write the second
      * and all subsequent blocks */
     if (!p->first && !pa_stream_get_timing_info(p->stream))
         return;
-    
+
     length = pa_stream_writable_size(p->stream);
-    
+
     while (length > 4) {
         size_t l = length;
 
         if (l > BUFSIZE)
             l = BUFSIZE;
-        
+
         l &= ~ ((size_t) 3);
 
         FPI_SoundOutput_FillBuffer(p, (char*) p->buf, l);
@@ -880,7 +880,12 @@ static void write_data(struct output_data *p) {
             break;
     }
 
-    /* The handling of errors here is just ridicilous. Blame Adobe! */
+    /* There's no real handling of errors here. Unfortunately the
+     * Flash API doesn't export a sane way to do this. With networked
+     * audio streams and hotplug-capable audio devices the audio
+     * stream might be killed in the middle of nothing, hence it is
+     * very unfortunate that we cannot report errors that happen here
+     * back to Flash. */
 
     p->first = 0; /* So, we write the first block noch, remember that */
 }
@@ -913,16 +918,21 @@ static void stream_latency_update_cb(pa_stream *s, void *userdata) {
 static void *FPX_SoundOutput_Open(void) {
 
     static const pa_sample_spec ss = {
-        .format = PA_SAMPLE_S16LE, /* Hmm, Flash wants LE here, not NE. I hope they know what they are doing. Probably not. */
+        .format = PA_SAMPLE_S16LE, /* Hmm, Flash wants LE here, not
+                                    * NE. This makes porting Flash to
+                                    * Big-Endian machines unnecessary
+                                    * difficult. */
         .rate = 44100,
         .channels = 2
     };
 
     struct output_data *p;
-    
-    /* Awesome, we don't inform the user about any error messages, I
-     * guess that's Adobe style programming. Rock!" */
-    
+
+    /* Unfortunately we cannot report any useful error string back to
+     * Flash. It would be highly preferable if Flash supported some
+     * way how we could tell the user what the reason is why audio is
+     * not working for him. */
+
     if (!(p = FPI_Mem_Alloc(sizeof(struct output_data))))
         goto fail;
 
@@ -939,7 +949,7 @@ static void *FPX_SoundOutput_Open(void) {
         goto fail;
 
     pa_context_set_state_callback(p->context, context_state_cb, p);
-    
+
     if (pa_context_connect(p->context, NULL, 0, NULL) < 0)
         goto fail;
 
@@ -979,7 +989,7 @@ static void *FPX_SoundOutput_Open(void) {
 unlock_and_fail:
 
     pa_threaded_mainloop_unlock(p->mainloop);
-    
+
 fail:
     if (p)
         FPX_SoundOutput_Close(p);
@@ -991,7 +1001,7 @@ static int FPX_SoundOutput_Close(void *ptr) {
     struct output_data *p = ptr;
 
     assert(p);
-    
+
     if (p->mainloop)
         pa_threaded_mainloop_stop(p->mainloop);
 
@@ -1007,7 +1017,7 @@ static int FPX_SoundOutput_Close(void *ptr) {
 
     if (p->mainloop)
         pa_threaded_mainloop_free(p->mainloop);
-    
+
     if (FPI_Mem_Free)
         FPI_Mem_Free(p);
 
@@ -1025,7 +1035,7 @@ static int FPX_SoundOutput_Latency(void *ptr) {
     /* We lock here only if we are not called from our event loop thread */
     if (!p->thread_id || !pthread_equal(p->thread_id, pthread_self()))
         pa_threaded_mainloop_lock(p->mainloop);
-    
+
     if (pa_stream_get_latency(p->stream, &t, &negative) < 0 || negative)
         r = 0;
     else
@@ -1033,7 +1043,7 @@ static int FPX_SoundOutput_Latency(void *ptr) {
 
     if (!p->thread_id || !pthread_equal(p->thread_id, pthread_self()))
         pa_threaded_mainloop_unlock(p->mainloop);
-    
+
     return r;
 }