changeset 26132:9df8c729e2e7

hgweb: add some documentation

It took longer than I wanted to grok how the various parts of hgweb
worked. So I added some class and method documentation to help whoever
hacks on this next.

--- a/mercurial/hgweb/hgweb_mod.py	Tue Sep 01 23:35:06 2015 +0800
+++ b/mercurial/hgweb/hgweb_mod.py	Sat Aug 22 13:58:59 2015 -0700
@@ -62,6 +62,16 @@
 
 
 class hgweb(object):
+    """HTTP server for individual repositories.
+
+    Instances of this class serve HTTP responses for a particular
+    repository.
+
+    Instances are typically used as WSGI applications.
+
+    Some servers are multi-threaded. On these servers, there may
+    be multiple active threads inside __call__.
+    """
     def __init__(self, repo, name=None, baseui=None):
         if isinstance(repo, str):
             if baseui:
@@ -157,6 +167,11 @@
             self.repo.ui.environ = request.env
 
     def run(self):
+        """Start a server from CGI environment.
+
+        Modern servers should be using WSGI and should avoid this
+        method, if possible.
+        """
         if not os.environ.get('GATEWAY_INTERFACE', '').startswith("CGI/1."):
             raise RuntimeError("This function is only intended to be "
                                "called while running as a CGI script.")
@@ -164,11 +179,19 @@
         wsgicgi.launch(self)
 
     def __call__(self, env, respond):
+        """Run the WSGI application.
+
+        This may be called by multiple threads.
+        """
         req = wsgirequest(env, respond)
         return self.run_wsgi(req)
 
     def run_wsgi(self, req):
+        """Internal method to run the WSGI application.
 
+        This is typically only called by Mercurial. External consumers
+        should be using instances of this class as the WSGI application.
+        """
         self.refresh(req)
 
         # work with CGI variables to create coherent structure

--- a/mercurial/hgweb/hgwebdir_mod.py	Tue Sep 01 23:35:06 2015 +0800
+++ b/mercurial/hgweb/hgwebdir_mod.py	Sat Aug 22 13:58:59 2015 -0700
@@ -79,6 +79,13 @@
     return name, str(port), path
 
 class hgwebdir(object):
+    """HTTP server for multiple repositories.
+
+    Given a configuration, different repositories will be served depending
+    on the request path.
+
+    Instances are typically used as WSGI applications.
+    """
     def __init__(self, conf, baseui=None):
         self.conf = conf
         self.baseui = baseui

--- a/mercurial/hgweb/request.py	Tue Sep 01 23:35:06 2015 +0800
+++ b/mercurial/hgweb/request.py	Sat Aug 22 13:58:59 2015 -0700
@@ -40,6 +40,12 @@
     return form
 
 class wsgirequest(object):
+    """Higher-level API for a WSGI request.
+
+    WSGI applications are invoked with 2 arguments. They are used to
+    instantiate instances of this class, which provides higher-level APIs
+    for obtaining request parameters, writing HTTP output, etc.
+    """
     def __init__(self, wsgienv, start_response):
         version = wsgienv['wsgi.version']
         if (version < (1, 0)) or (version >= (2, 0)):