[Bug 65861] New: Document how the post_config hook is called

https://bz.apache.org/bugzilla/show_bug.cgi?id=65861

            Bug ID: 65861
           Summary: Document how the post_config hook is called
           Product: Apache httpd-2
           Version: 2.5-HEAD
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
          Assignee: [email protected]
          Reporter: [email protected]
  Target Milestone: ---

I've been able to find little information on the post_config hook in the
project's documentation (doxygen, website, etc.).

I did find <https://cwiki.apache.org/confluence/display/HTTPD/ModuleLife>, but
I don't know whether that page is up-to-date, considering that it hasn't been
edited at least since it was imported from moin.

The following patch fleshes out the API documentation a bit.

Issues:

1. Does not explain what post_config hooks are expected to do / not do in a
pre-config invocation.  Is that assumed knowledge?  Is there an explanation of
this elsewhere that can be pointed to?

2. A period may need to be added after the words "for each module".  I haven't
run doxygen(1) on the file to check this.

3. The documentation of ap_state_query()-related macros includes some
non-doxygen'd comments (/*…*/ rather than /**…*/), so API users will need to
review the raw .h file to get all information.



[[[
Index: include/http_config.h
===================================================================
--- include/http_config.h       (revision 1897551)
+++ include/http_config.h       (working copy)
@@ -1350,6 +1350,16 @@ AP_DECLARE_HOOK(void,test_config,(apr_pool_t *pcon

 /**
  * Run the post_config function for each module
+ *
+ * The function might be called multiple times.  @a pconf, @a plog, and
+ * @a ptemp may be cleared and/or destroyed between calls.
+ *
+ * The function will be called zero or one times with the server's state being
+ * #AP_SQ_MS_CREATE_PRE_CONFIG, and will be called one or more times with
+ * the server's state being #AP_SQ_MS_CREATE_CONFIG.
+ *
+ * @see ap_state_query(), #AP_SQ_MAIN_STATE
+ *
  * @param pconf The config pool
  * @param plog The logging streams pool
  * @param ptemp The temporary pool
]]]

-- 
You are receiving this mail because:
You are the assignee for the bug.