diff --git a/lib/nghttp2_session.c b/lib/nghttp2_session.c
index 6e815ca2..d969d9fd 100644
--- a/lib/nghttp2_session.c
+++ b/lib/nghttp2_session.c
@@ -661,6 +661,13 @@ int nghttp2_session_reprioritize_stream(
   }
 
   if (dep_stream == stream->dep_prev && !pri_spec->exclusive) {
+    /* This is minor optimization when just weight is changed.
+       Currently, we don't reschedule stream in this case, since we
+       don't retain enough information to do that
+       (descendant_last_cycle we used to schedule it).  This means new
+       weight is only applied in the next scheduling, and if weight is
+       drastically increased, library is not responding very quickly.
+       If this is really an issue, we will do workaround for this. */
     dep_stream->sum_dep_weight += pri_spec->weight - stream->weight;
     stream->weight = pri_spec->weight;
     return 0;
diff --git a/lib/nghttp2_stream.c b/lib/nghttp2_stream.c
index b0cd4652..f83265b7 100644
--- a/lib/nghttp2_stream.c
+++ b/lib/nghttp2_stream.c
@@ -207,6 +207,11 @@ void nghttp2_stream_reschedule(nghttp2_stream *stream) {
       dep_stream->descendant_last_cycle = 0;
       stream->cycle = 0;
     } else {
+      /* We update descendant_last_cycle here, and we don't do it when
+         no data is written for stream.  This effectively means that
+         we treat these streams as if they are not scheduled at all.
+         This does not cause disruption in scheduling machinery.  It
+         just makes new streams scheduled a bit early. */
       dep_stream->descendant_last_cycle = stream->cycle;
 
       stream->cycle =