Re: squid-3 ?
On Thu, 2007-08-16 at 09:20 +1200, Amos Jeffries wrote: > > On Wed, 2007-08-15 at 09:58 +0200, Guido Serassio wrote: > > > >> Currently Squid is broken on all platforms without strtoll(), HP Tru64 > >> is one. > >> I'm working on it, and I'm expecting to fix the problem and run some > >> tests on other platforms (Irix, NetBSD and OpenBSD) within the > >> incoming weekend. > > > > Sounds good, thank you. > > > >> I think that we must wait for two weeks to see if the latest > >> large-objects changes are reasonably stable. > > > > I think we should release an RC1 snapshot now. > > I was a bit undecided yesterday. I kind of want to wait a short while to > see if large-obj is stable enough, but not enough to speak up. > > But with strtoll as Guido said, I think its clearly too early for an RC. > PRE7 at the end of this week I would agree with if there are no other > majors discovered before then. > > As I see it a PRE is considered 'mostly usable'. But for a full RC I think > we should be certain it actually is good quality (for some new definition > of good ;-), I suppose). My understanding is that the unfiled(?) strtoll bug affects only a subset of platforms. RC1 can exclude those platforms from the supported list. However, if we indeed are going to have a fix this weekend and can agree to move forward to RC1 right after that (if there are no other showstoppers), I can live with that. There are probably some things that we need to do in preparation for an RC snapshot anyway. The primary idea behind RC1 is to bring in users who are ignoring PRE releases because there were so many PREs. We need more testers than a handful of folks running PREs on busy sites. Alex.
Re: Documenting non-public members
On Thu, 2007-08-16 at 10:40 +1200, Amos Jeffries wrote: > Most of the squid code is commented for programmers in the .cc where the > code is written. Leaving that as-is where possible, this is actual more > convenient for most functions as editors can change code and description > in one place. > > BUT, API stuff MUST be written in the .h since there is no guarantee of > the user(s) having time to find and read the .cc (or it even being > available). I am not sure how you distinguish code users from developers, but I agree that APIs (whatever that is) should be documented in (or its documentation should be referenced from) .h files. > > There is simply > > no other good place to document them because there is no corresponding > > definition. > > There is the place where the {...} code itself lives. Which is the written > intention there. I picked this because that is the current documenting > style for squid. Class data members do not have a single place where they live inside the code. IMO, virtually every data member should be briefly documented in the .h file. If one cannot express what the data member "means" in one short line, it is a good indication of a poor design. Similar things can be said about groups of data and function members: There is no place to document groupings in .cc file because member definitions are far from each other. > The edge case here is virtual functions defined as virtual foo Bar(){} in > the .h file itself. > Those needs a brief comment saying class X defined as empty or do-nothing. Actually, placing a .h comment that bar() implementation does nothing is a dangerous practice! The child should not care or rely upon specific parent's implementation of a virtual method because that implementation may change. What does matter for the child is whether the parent method should be called by the child. And, sometimes, whether it should be called before or after the child code. > > A short description of methods should also be appropriate (and is often > > very helpful) in .h file, even if they are not a part of public API. > > True, we can do this regardless of where the detail description is. ANY > auto-docs comment in .h or .cc(i) just ahead of a object-name are > catenated for the final product. It is much easier for me to find short member descriptions/briefs in a .h file than in a .cc file, but if somebody is browsing doxygen pages, there should indeed be no difference. My rule of thumb is to place API descriptions and "what is it?" briefs in .h files and "how/why/etc" implementation notes in .cc files. Cheers, Alex.
Re: Code documentation trends
On Thu, 2007-08-16 at 10:21 +1200, Amos Jeffries wrote: > What I'm hoping for is to have a paragraph for each class about where its > intended to be used etc. That would be terrific! I was trying to provide that for the classes I was adding. > Theres lots of little bits still need doing for the Mem component. > You can see what it looks like at: > http://squid.treenet.co.nz/Doc/Code/MemPool_8h.dyn#2eab9a6fa490ed8426a1800e0ec4 > > I think maybe it's the text-description not making it clear its a > code-example. That description needs fixing. Yeah, I can hardly grok the current doxygen rendering. Said that, I care more about how .h looks, and the change makes it look "worse", IMO. Perhaps it will all be much better after the next round of "fixing", but I fear that I will spend more time trying to find and understand things before the doxygen invasion. But again, this is not a huge deal. > > None of these changes are a big deal, of course. I am just worried about > > the general trend of hiding code behind overly verbose documentation... > > > > Does doxygen support some kind of \include mechanism where verbose > > documentation can be moved away from the code while still being linked > > to specific code pieces? Detailed documentation is great, but if it > > makes the actual code difficult to see, it is doing more harm than good, > > IMO. > > Yes, but that defeats the entire purpose of this project. Having the > documentation at the point of code where it will get noticed for change by > any average-joe editors altering that code. I don't expect it to be huge. Yes, I understand the motivation, but every solution taken to the extreme becomes a problem. For example, it would be clearly inappropriate to explain what a C++ class means or how a C++ macro works next to every (or any!) Squid class or macro declaration. Similarly, inserting a chapter on Squid performance optimization next to StoreEntry declaration is wrong. Overly verbose comments are almost as bad as the missing ones. We should not forget that correct, maintainable _code_ is the primary goal. Good code should not require many verbose comments. And too many verbose comments obscure good code. Again, these are general trend-setting observations. The specific example that prompted me to write this is not the most extreme case of verbosity. > I've had a hard time converting the SGML because it references only 2.5 > examples and function names, describing how they behave in 2.5, and had to > check each function operation and change some of it in migration. Sure. And there are lots of obsolete comments in Squid _sources_ as well! Alex.
Re: Documenting non-public members
(pulling this back into squid-dev. private response was a slip of the paste key.) > On Thu, 2007-08-16 at 10:40 +1200, Amos Jeffries wrote: > >> Most of the squid code is commented for programmers in the .cc where the >> code is written. Leaving that as-is where possible, this is actual more >> convenient for most functions as editors can change code and description >> in one place. >> >> BUT, API stuff MUST be written in the .h since there is no guarantee of >> the user(s) having time to find and read the .cc (or it even being >> available). > > I am not sure how you distinguish code users from developers, but I Ah, I mean "user" as someone writing code (A) somewhere than needs to use an object (B)s' interface to make it do stuff. Rather than writing new code inside object B itself. > agree that APIs (whatever that is) should be documented in (or its > documentation should be referenced from) .h files. > >> > There is simply >> > no other good place to document them because there is no corresponding >> > definition. >> >> There is the place where the {...} code itself lives. Which is the >> written >> intention there. I picked this because that is the current documenting >> style for squid. > > Class data members do not have a single place where they live inside the > code. IMO, virtually every data member should be briefly documented in > the .h file. If one cannot express what the data member "means" in one > short line, it is a good indication of a poor design. > > Similar things can be said about groups of data and function members: > There is no place to document groupings in .cc file because member > definitions are far from each other. > >> The edge case here is virtual functions defined as virtual foo Bar(){} >> in >> the .h file itself. >> Those needs a brief comment saying class X defined as empty or >> do-nothing. > > Actually, placing a .h comment that bar() implementation does nothing is > a dangerous practice! The child should not care or rely upon specific > parent's implementation of a virtual method because that implementation > may change. What does matter for the child is whether the parent method > should be called by the child. And, sometimes, whether it should be > called before or after the child code. > >> > A short description of methods should also be appropriate (and is >> often >> > very helpful) in .h file, even if they are not a part of public API. >> >> True, we can do this regardless of where the detail description is. ANY >> auto-docs comment in .h or .cc(i) just ahead of a object-name are >> catenated for the final product. > > It is much easier for me to find short member descriptions/briefs in > a .h file than in a .cc file, but if somebody is browsing doxygen pages, > there should indeed be no difference. > > My rule of thumb is to place API descriptions and "what is it?" briefs > in .h files and "how/why/etc" implementation notes in .cc files. ... Um... Thats the way I had it. Amos
Re: IPv6 support and Windows
> Hi Amos, > > At 07.25 15/08/2007, Amos Jeffries wrote: >> >> Hi Amos, >> >> >> >> Not good news here ... :-( >> >> >> >> We have a problem: >> >> You have used getaddrinfo() and freeaddrinfo() functions, but on >> >> Windows they are available only starting from Windows XP. This means >> >> that your code, even if compiled without IPv6 support, cannot run on >> >> Windows 2000. >> >> >> >> I'm also not sure if getaddrinfo() and freeaddrinfo() functions are >> >> available on all systems, someone know something about ? >> > >> >>I have just imported and properly wrapped the libesmtp getaddrinfo and >>supporting implementation from fetchmail 6.3.8. >> >>I have done some simple configure and compile tests here. Its time to >> pass >>it back to you Guido for the win32 test. > > I think that will be better for us to use a wrapper for the > functions, something like squid-getaddrinfo(), this will allow a > simpler usage on Windows (see my previous mail). True. x seems to be the preferred prefix. I'll also see about wrap/include of the dependancy functions individually. ANYONE: Is anyone able to confirm for me whether I'm supposed to be using AC_SEARCH_LIBS() or AC_FUNC_CHECK() to do that properly? > >>I'm kind of expecting another set of errors off these. It's just a matter >>of which ones. > > For now look for an undefined "IPv6" into ACLIP.cc (line 296). Fixed. > > See tomorrow, I'm going to a barbecue with friends, today in Italy is > a Holiday. :-) > happy holiday :-) Amos
Re: Documenting non-public members
> > I noticed this in a recent squid3/doc/Programming-Guide commit message: > >> \section Coding Code Conventions > ... >> Now that documentation is generated automatically from the sources >> some common comment conventions need to be adopted. >> >> \subsectionAPI vs Internal Component Commenting > ... >> First among these is a definition seperation between component API >> and Internal operations. API functions and objects should always be >> commented and in the *.h file for the component. Internal logics and >> objscte should be commented in the *.cc file wherever they are >> defined. > > I am not sure this is a good guideline for C++ because class data > members should be briefly documented where they are declared (which is > in the .h file), even if they are not a part of the API. This is perhapse due more discussion amongst us all. My view so far is: Most of the squid code is commented for programmers in the .cc where the code is written. Leaving that as-is where possible, this is actually more convenient for most functions where editors can change code and description in one place. BUT, API stuff MUST be written in the .h since there is no guarantee of the user(s) having time to find and read the .cc (or it even being available). If we all agree that .h is the place for class internal docs, I'll accept it. But do consider the convenience factor in mind for all future maintainers when deciding. > There is simply > no other good place to document them because there is no corresponding > definition. There is the place where the {...} code itself lives. Which is the written intention there. I picked this because that is the current documenting style for squid. The edge case here is virtual functions defined as virtual foo Bar(){} in the .h file itself. Those needs a brief comment saying class X defined as empty or do-nothing. (doxygen will, as currently set, pull the parent class docs for a method into the childs. Thus the parent has full description, child has mod notes) > A short description of methods should also be appropriate (and is often > very helpful) in .h file, even if they are not a part of public API. True, we can do this regardless of where the detail description is. ANY auto-docs comment in .h or .cc(i) just ahead of a object-name are catenated for the final product. > > $0.02, and $0.01 bank fees ;-) Amos
Re: Code documentation trends
> On Wed, 2007-08-15 at 02:32 +, Amos Jeffries wrote: >> *** MemPool.h23 Jun 2007 01:43:43 - 1.10.10.1 >> --- MemPool.h15 Aug 2007 02:32:57 - 1.10.10.2 >> *** >> *** 120,124 >> }; >> >> ! /* Support late binding of pool type for allocator agnostic classes */ >> class MemAllocatorProxy >> { >> --- 120,126 >> }; >> >> ! /** >> ! * Support late binding of pool type for allocator agnostic classes >> ! */ > > Did you add the two extra lines to make doxygen happy? Is there a less > invasive way to accomplish the same? (Please do not interpret these > questions as criticism, I am just trying to understand the motivation > and doxygen limitations). No, a block doc-comment only requires the /** at the beginning , everything else is arrangement and visual effect. The extra lines like that are usually because I expect a full description to go in there. Will be happening to all API stuff in .h, much less so on Internals. That one is also going to need a few doxygen tags like \ingroup and a less-cryptic description. I didn't quite get time last night to go through the Mem* component pieces and link them into a module. Time for part 2 of the auto-docs lessons: What I have settled on a week ago is a 'looks nice and can be read easily' style, which requires people only to know that doc comments start with /** and have " * " at the start of each line inside the comment. Lines that start with " \foo" are special to the auto-docs and only to be altered if understood (doxygen help is online for reference). Do make any special formatting such as lists, paragraphing, large titles, example code snippets require the doxygen commands. Formatting by whitespace indentation (ie " - ") will no longer work. What I'm hoping for is to have a paragraph for each class about where its intended to be used etc. Objects where I only have enough details to say this is part of X module, are going in as "/// ..." for now (which I would like NOT to have in the final code pushed to HEAD, its quite ugly to see "/// \FooBarInternals", but it works). Part 3 (module/component names and organisation, will have to come later when I have a more certain list). > >> class MemAllocatorProxy >> { >> *** >> *** 138,143 >> mutable MemAllocator *theAllocator; >> }; >> /* help for classes */ >> ! /* Put this in the class */ >> #define MEMPROXY_CLASS(CLASS) \ >> /* TODO change syntax to allow moving into .cci files */ \ >> --- 140,154 >> mutable MemAllocator *theAllocator; >> }; >> + >> /* help for classes */ >> ! /** >> ! * Put this in the class >> ! \code >> !class foo >> !{ >> ! MEMPROXY_CLASS(foo); >> !} >> ! \endcode >> ! */ >> #define MEMPROXY_CLASS(CLASS) \ >> /* TODO change syntax to allow moving into .cci files */ \ > > Does this change work around some other doxygen limitation? Or are you > trying to provide a better illustration of what "Put this in the class" > means? I was just copying the 'how to use' example as-is from the old SGML file. \code and \endcode just tell doxygen its a piece of example code to be displayed. Theres lots of little bits still need doing for the Mem component. You can see what it looks like at: http://squid.treenet.co.nz/Doc/Code/MemPool_8h.dyn#2eab9a6fa490ed8426a1800e0ec4 I think maybe it's the text-description not making it clear its a code-example. That description needs fixing. > > None of these changes are a big deal, of course. I am just worried about > the general trend of hiding code behind overly verbose documentation... > > Does doxygen support some kind of \include mechanism where verbose > documentation can be moved away from the code while still being linked > to specific code pieces? Detailed documentation is great, but if it > makes the actual code difficult to see, it is doing more harm than good, > IMO. Yes, but that defeats the entire purpose of this project. Having the documentation at the point of code where it will get noticed for change by any average-joe editors altering that code. I don't expect it to be huge. I've had a hard time converting the SGML because it references only 2.5 examples and function names, describing how they behave in 2.5, and had to check each function operation and change some of it in migration. > >> *** >> *** 146,150 >> static inline MemAllocatorProxy &Pool() >> >> ! /* put this in the class .h, or .cci as appropriate */ >> #define MEMPROXY_CLASS_INLINE(CLASS) \ >> MemAllocatorProxy& CLASS::Pool() \ >> --- 157,171 >> static inline MemAllocatorProxy &Pool() >> >> ! /** >> ! * Put this in the class .h, or .cci as appropriate >> ! \code >> !class foo >> !{ >> ! MEMPROXY_CLASS(foo); >> !} >> ! >> !MEMPROXY_CLASS_INLINE(foo); >> ! \endcode >> ! */ >> #define MEMPROXY_CLASS_INLINE(CLASS) \ >> MemAllocatorProxy& CLASS::Pool() \ > > Like this new docume
Re: squid-3 ?
> On Wed, 2007-08-15 at 09:58 +0200, Guido Serassio wrote: > >> Currently Squid is broken on all platforms without strtoll(), HP Tru64 >> is one. >> I'm working on it, and I'm expecting to fix the problem and run some >> tests on other platforms (Irix, NetBSD and OpenBSD) within the >> incoming weekend. > > Sounds good, thank you. > >> I think that we must wait for two weeks to see if the latest >> large-objects changes are reasonably stable. > > I think we should release an RC1 snapshot now. I was a bit undecided yesterday. I kind of want to wait a short while to see if large-obj is stable enough, but not enough to speak up. But with strtoll as Guido said, I think its clearly too early for an RC. PRE7 at the end of this week I would agree with if there are no other majors discovered before then. As I see it a PRE is considered 'mostly usable'. But for a full RC I think we should be certain it actually is good quality (for some new definition of good ;-), I suppose). Amos
Documenting non-public members
I noticed this in a recent squid3/doc/Programming-Guide commit message: > \section Coding Code Conventions ... > Now that documentation is generated automatically from the sources > some common comment conventions need to be adopted. > > \subsection API vs Internal Component Commenting ... > First among these is a definition seperation between component API > and Internal operations. API functions and objects should always be > commented and in the *.h file for the component. Internal logics and > objscte should be commented in the *.cc file wherever they are defined. I am not sure this is a good guideline for C++ because class data members should be briefly documented where they are declared (which is in the .h file), even if they are not a part of the API. There is simply no other good place to document them because there is no corresponding definition. A short description of methods should also be appropriate (and is often very helpful) in .h file, even if they are not a part of public API. $0.02, Alex.
Code documentation trends
On Wed, 2007-08-15 at 02:32 +, Amos Jeffries wrote: > Update of cvs.devel.squid-cache.org:/cvsroot/squid/squid3/include > > Modified Files: > Tag: docs > MemPool.h > Log Message: > Commenting style change. > > > Index: MemPool.h > === > RCS file: /cvsroot/squid/squid3/include/MemPool.h,v > retrieving revision 1.10.10.1 > retrieving revision 1.10.10.2 > diff -C2 -d -r1.10.10.1 -r1.10.10.2 > *** MemPool.h 23 Jun 2007 01:43:43 - 1.10.10.1 > --- MemPool.h 15 Aug 2007 02:32:57 - 1.10.10.2 > *** > *** 120,124 > }; > > ! /* Support late binding of pool type for allocator agnostic classes */ > class MemAllocatorProxy > { > --- 120,126 > }; > > ! /** > ! * Support late binding of pool type for allocator agnostic classes > ! */ Did you add the two extra lines to make doxygen happy? Is there a less invasive way to accomplish the same? (Please do not interpret these questions as criticism, I am just trying to understand the motivation and doxygen limitations). > class MemAllocatorProxy > { > *** > *** 138,143 > mutable MemAllocator *theAllocator; > }; > /* help for classes */ > ! /* Put this in the class */ > #define MEMPROXY_CLASS(CLASS) \ > /* TODO change syntax to allow moving into .cci files */ \ > --- 140,154 > mutable MemAllocator *theAllocator; > }; > + > /* help for classes */ > ! /** > ! * Put this in the class > ! \code > !class foo > !{ > ! MEMPROXY_CLASS(foo); > !} > ! \endcode > ! */ > #define MEMPROXY_CLASS(CLASS) \ > /* TODO change syntax to allow moving into .cci files */ \ Does this change work around some other doxygen limitation? Or are you trying to provide a better illustration of what "Put this in the class" means? None of these changes are a big deal, of course. I am just worried about the general trend of hiding code behind overly verbose documentation... Does doxygen support some kind of \include mechanism where verbose documentation can be moved away from the code while still being linked to specific code pieces? Detailed documentation is great, but if it makes the actual code difficult to see, it is doing more harm than good, IMO. > *** > *** 146,150 > static inline MemAllocatorProxy &Pool() > > ! /* put this in the class .h, or .cci as appropriate */ > #define MEMPROXY_CLASS_INLINE(CLASS) \ > MemAllocatorProxy& CLASS::Pool() \ > --- 157,171 > static inline MemAllocatorProxy &Pool() > > ! /** > ! * Put this in the class .h, or .cci as appropriate > ! \code > !class foo > !{ > ! MEMPROXY_CLASS(foo); > !} > ! > !MEMPROXY_CLASS_INLINE(foo); > ! \endcode > ! */ > #define MEMPROXY_CLASS_INLINE(CLASS) \ > MemAllocatorProxy& CLASS::Pool() \ Like this new documentation bug, for example. :-) Thank you, Alex.
Re: squid-3 ?
On Wed, 2007-08-15 at 09:58 +0200, Guido Serassio wrote: > Currently Squid is broken on all platforms without strtoll(), HP Tru64 is one. > I'm working on it, and I'm expecting to fix the problem and run some > tests on other platforms (Irix, NetBSD and OpenBSD) within the > incoming weekend. Sounds good, thank you. > I think that we must wait for two weeks to see if the latest > large-objects changes are reasonably stable. I think we should release an RC1 snapshot now. Alex.
Re: squid-3 ?
Hi Adrian, At 10.04 15/08/2007, Adrian Chadd wrote: On Wed, Aug 15, 2007, Guido Serassio wrote: > I think that we must wait for two weeks to see if the latest > large-objects changes are reasonably stable. I was wondering about that. I thought 3.0 was reasonably frozen.. anyway, I'll continue lurking. But still not so stable see my commits done yesterday ... :-) This was the first chunk. Regards Guido Serassio - Guido Serassio Acme Consulting S.r.l. - Microsoft Certified Partner Via Lucia Savarino, 1 10098 - Rivoli (TO) - ITALY Tel. : +39.011.9530135 Fax. : +39.011.9781115 Email: [EMAIL PROTECTED] WWW: http://www.acmeconsulting.it/
Re: squid-3 ?
On Wed, Aug 15, 2007, Guido Serassio wrote: > I think that we must wait for two weeks to see if the latest > large-objects changes are reasonably stable. I was wondering about that. I thought 3.0 was reasonably frozen.. anyway, I'll continue lurking. Adrian
Re: squid-3 ?
Hi Adrian, At 07.43 15/08/2007, Adrian Chadd wrote: How long before the next pre or release candidate of squid-3 ? Currently Squid is broken on all platforms without strtoll(), HP Tru64 is one. I'm working on it, and I'm expecting to fix the problem and run some tests on other platforms (Irix, NetBSD and OpenBSD) within the incoming weekend. I think that we must wait for two weeks to see if the latest large-objects changes are reasonably stable. Regards Guido - Guido Serassio Acme Consulting S.r.l. - Microsoft Certified Partner Via Lucia Savarino, 1 10098 - Rivoli (TO) - ITALY Tel. : +39.011.9530135 Fax. : +39.011.9781115 Email: [EMAIL PROTECTED] WWW: http://www.acmeconsulting.it/
Re: IPv6 support and Windows
Hi Amos, At 00.13 15/08/2007, Amos Jeffries wrote: > Hi Amos, > > Not good news here ... :-( > > We have a problem: > You have used getaddrinfo() and freeaddrinfo() functions, but on > Windows they are available only starting from Windows XP. This means > that your code, even if compiled without IPv6 support, cannot run on > Windows 2000. > > I'm also not sure if getaddrinfo() and freeaddrinfo() functions are > available on all systems, someone know something about ? We have already tested Linux 2.6+ and FreeBSD 4.5+ (4.3 _says_ it has them) Not sure about Solaris, OS2, or Darwin yet. We also must check OpenBSD, NetBSD, Tru64, Irix and AIX. I have the first four. > I have found two interesting substitute here: > > http://doxygen.postgresql.org/getaddrinfo_8c-source.html > > I'm not sure if the licensing of the implementation coming from the > PostgreSQL allow its usage in Squid. > PostGres looks good until I audit the code. These are both killer bugs for us: " Bugs: - only one addrinfo is set even though hintp is NULL or ai_socktype is 0 - AI_CANONNAME is not supported. " > http://www.koders.com/c/fid11C8C256BE9D1C263E0725F657383F62F24759F5.aspx?s=md5 The very first line says it's a (partial) implementation which makes me think there are edge cases missing, etc. Though a quick check of the code I couldn't see any obvious problems or notes about killer bugs. I'm sure there are more re-writes around, and sure enough Google codesearch find me a clean fetchmail implementation of JUST getaddrinfo(), freeaddrinfo() and gai_strerror(). ftp://ftp.sunfreeware.com/pub/freeware/SOURCES/fetchmail-6.3.6.tar.gz&cs_f=fetchmail-6.3.6/libesmtp/getaddrinfo.c#a0 That is probably better for us being more complete in the IPv4-area. The crunch now will be whether getnameinfo() is also that unsupported in NT/2k ? We must mix this code with the PostgreSQL one: on Windows the usage of native functions when available is mandatory. And sure, also getnameinfo() is not available on Windows 2000. Regards Guido - Guido Serassio Acme Consulting S.r.l. - Microsoft Certified Partner Via Lucia Savarino, 1 10098 - Rivoli (TO) - ITALY Tel. : +39.011.9530135 Fax. : +39.011.9781115 Email: [EMAIL PROTECTED] WWW: http://www.acmeconsulting.it/