Re: [DOCS] C code documentation
Dan Sugalski wrote: Michael Scott wrote: Perhaps the most controversial feature of all this is that I'm using rows of 80 '#'s as visual delimiters to distinguish documentation sections from code. Please don't. If you really, really must, chop it down to 60 or so characters. 80 may wrap in some editors under some situations, and anything bigger than 72 may trigger wrapping behaviour in mail programs. (I think I'd as soon you didn't put in delimiters like this at all, but I can live with it if I must) And more than 71 and messages containing patch snippets will wrap in some mail programs. And more than 69 and replies to messages containing patch snippets will wrap in some mail programs. ad infinitum... Gordon Henriksen [EMAIL PROTECTED]
Re: [DOCS] C code documentation
At 10:42 AM +0100 1/21/04, Michael Scott wrote: Perhaps the most controversial feature of all this is that I'm using rows of 80 '#'s as visual delimiters to distinguish documentation sections from code. Please don't. If you really, really must, chop it down to 60 or so characters. 80 may wrap in some editors under some situations, and anything bigger than 72 may trigger wrapping behaviour in mail programs. (I think I'd as soon you didn't put in delimiters like this at all, but I can live with it if I must) -- Dan --it's like this--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: [DOCS] C code documentation
Yep. I bounced Sam's comment around in my head for a while until I saw that I was only putting them in for my own current convenience - makes it easier to see what I'm doing as I'm doing it - so they won't be there. Minimal is best. And anyway who wants to be SO 20th century. Mike On 22 Jan 2004, at 19:33, Dan Sugalski wrote: At 10:42 AM +0100 1/21/04, Michael Scott wrote: Perhaps the most controversial feature of all this is that I'm using rows of 80 '#'s as visual delimiters to distinguish documentation sections from code. Please don't. If you really, really must, chop it down to 60 or so characters. 80 may wrap in some editors under some situations, and anything bigger than 72 may trigger wrapping behaviour in mail programs. (I think I'd as soon you didn't put in delimiters like this at all, but I can live with it if I must) -- Dan --it's like this--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
[DOCS] C code documentation
PDD 7 Conventions and Guidelines for Parrot Source Code has a section on Code Comments that has been followed for C code. I'm about to change this. The existing documentation headers will be replaced with pod headers contained within C multi-line comment delimiters. I'm going to stick to exactly the same style that I used in the Perl scripts. Functions will be proceeded with similarly formatted descriptions. No information will be lost. Perhaps the most controversial feature of all this is that I'm using rows of 80 '#'s as visual delimiters to distinguish documentation sections from code. This may seem like overkill to some. I'm basing it on what looks right to me in BBEdit and Xcode. If it turns out that it doesn't work for everyone, I'll change it. If anyone feels strongly about this then speak. Mike
Re: [DOCS] C code documentation
My vote goes for the simplest that will still parse; /* =head1 foo */ After all, arent't we all using editors that can highlight the scructure of our code to our satisfaction ? Surely even VIM et al can stick in dividers or something to make them stand out if the coder desires? I've already got __ | |__(_)__ _ | '_ \ / _` | |_.__/_\__, | fonts set for my POD headings, |___/ which is a lot nicer to work with (IMHoHO). ASCII art delimiters in code are SO 20th century ;-) ___ __ _ / \ | | ( ( ( 2ยข ) | | ___ \__/ |_| On Wed, 21 Jan 2004 22:42, Michael Scott wrote; PDD 7 Conventions and Guidelines for Parrot Source Code has a section on Code Comments that has been followed for C code. I'm about to change this. The existing documentation headers will be replaced with pod headers contained within C multi-line comment delimiters. I'm going to stick to exactly the same style that I used in the Perl scripts. Functions will be proceeded with similarly formatted descriptions. No information will be lost. Perhaps the most controversial feature of all this is that I'm using rows of 80 '#'s as visual delimiters to distinguish documentation sections from code. This may seem like overkill to some. I'm basing it on what looks right to me in BBEdit and Xcode. If it turns out that it doesn't work for everyone, I'll change it. If anyone feels strongly about this then speak. Mike -- Sam Vilain, [EMAIL PROTECTED] Real software engineers don't debug programs, they verify correctness. This process doesn't necessarily involve executing anything on a computer, except perhaps a Correctness Verification Aid package.
