API documentation?

[anarcat]

attic/borg has very little inline comments, but it would still be very useful to expose the API structure in the official documentation.

in fact, I wonder if it would be useful to spend some time crawling through that source code explaining each file and function so that we could get a better idea of what all the parts are doing...

then the sphinx doc engine could automatically generate nice API graphs that would be walkable.

the way i did that in one of my Python modules is like this:

Monkeysign API documentation
============================

GnuPG API
---------

.. automodule:: monkeysign.gpg
   :members:
   :undoc-members:

CLI Interface
-------------

.. automodule:: monkeysign.cli
   :members:
   :undoc-members:

GTK Interface
-------------

.. may fail if the GTK module isn't available, oh well.
.. automodule:: monkeysign.gtkui
   :members:
   :undoc-members:

it's mostly useful to document APIs, but I think it could be useful for borg as well.

opinions?

[anarcat]

i can't work on this without uninstalling attic or fixing #24 so i am a little stuck.

[ThomasWaldmann]

Currently, better don't do global changes, like adding docstrings everywhere. That would just cause a lot of work when I merge all that still-unmerged code from "merge-all" branch.

[anarcat]

ack, no problem

[anarcat]

see #230 for the shims to build with the current docstrings (which isn't much). moving the discussion there.