diff --git a/py/apigen/todo.txt b/py/apigen/todo.txt
new file mode 100644
index 000000000..7f649f11f
--- /dev/null
+++ b/py/apigen/todo.txt
@@ -0,0 +1,50 @@
+
+* when listing the methods of a class: 
+  special "__*__" methods should come last except for __init__ 
+  which comes first 
+
+* the page header should read:
+  
+    py.path.local API documentation [rev XYZ]
+
+  instead of 
+
+    api documentation for path.local 
+
+* have the py/doc/ and apigen page layout have
+  an api and source link in the menu bar 
+  (e.g.: home doc api source contact getting-started issue)
+
+* function view: 
+
+     def __init__(self, rawcode):
+        docstring-in-grey-and-not-in-a-box
+
+  and the "show/hide funcinfo" link could be underyling
+  the full "def __init__(self, rawcode)" or be a link right after 
+  (or maybe before) it. 
+
+  goal: consume less vertical space and have the functions
+  be "sticking" out (the show/hide info link IMO disrupts this
+  and it's not visually clear it belongs to the function above it)
+
+* can it be avoided that py.execnet.Channel shows up as a
+  primary object but still have it documented/linked from 
+  remote_exec()'s "return value"? 
+
+* class attributes are not "properties". can they get their
+  section? 
+
+* stacktraces: a lot are "duplicates" like:
+
+    /home/hpk/py-trunk/py/test/rsession/hostmanage.py - line 37
+    /home/hpk/py-trunk/py/test/rsession/hostmanage.py - line 37
+    /home/hpk/py-trunk/py/test/rsession/hostmanage.py - line 37
+
+  even though they may reference different stackframes, 
+  i think we should by default strip out these duplicates,
+  this would also reduce the generated html files, right? 
+
+* allow for flexibility regarding linking from 
+  py/doc/*.txt documents to apigen with respect
+  to where apigen/ docs are located.