> >> I thought about this but here's why I went with one description. > >> First, the short definition (purpose) is already in the refpurpose > >> of the function. Also, writing a summary for each would be a bit > >> too difficult. As far as using just the first para, I think it'd > >> be confusing having it so far apart from the rest of the description > >> as they are often tied together. And something to keep in mind is > >> long descriptions are rare. > >> > >> I agree return values should go after the parameter list. So here's > >> my thoughts on the matter: > >> > >> Description (full) > >> Parameter List > >> Return Values > >> Changelog > >> Examples > >> See Also > >> > >> The changelog has important information, enough so that it should go > >> before the examples. I believe the only part that needs further > >> discussion and thought is the Description. > > > > > > Chagelog affects parameters, return values, and other types of > > behaviour, so it should be after the description of these IMHO. I am > > fine with Philip's above suggestion. > > Fine with me too.
Because this is such a major deal how about we wait a little while longer, let's say by the arbitrary date of August 16. If no other problems are seen it'll be go time! Silence assumes happiness. At that time the HOWTO will be rewritten (I'll do it), revised, and then the conversion process will begin. If we start out slow a few unsuspecting problems (and solutions) may crop up as we only want to do this once. How the curl_setopt() docs will look comes to mind, same for sprintf(). Regards, Philip
