Paste: rationale for directory-per-module

Author: kssreeram
Mode: text
Date: Sun, 29 Aug 2010 17:25:55
Plain Text |
In most programming languages the API documentation for a module is
inlined within the source code. I find that unsatisfactory for two reasons:

1) The documentation is itself difficult to read because it contains
   markup meant to make it look good when viewed in a browser.

2) In many cases the documentation is soo large that it interferes
   when trying to read the code.

So it's a good idea to keep the source code and the api documentation
in two separate files. This was the motivating reason for requiring a
separate directory for every module. The plan is to use the module's
directory for storing multiple different files related to the module
e.g: source code file + docs file + unit tests file

I borrowed this design from Factor.

New Annotation