Re: PDD for code comments ????
At 06:09 PM 3/27/2001 +0100, Dave Mitchell wrote: >Dan Sugalski <[EMAIL PROTECTED]> wrote: > > >I'm happy think that we're using a special extractor rather than pod - > > >cf embed.pl producing perlapi.pod. However, I'd rather a plain ^/*...^*/ > > >not be picked up. > > > > Same here. All the C comments ought not be picked up. /*=pod and =cut*/ > > pairs aren't a bad thing to go with, though. > >Given the laziness principle, I think that > >a) a simple */ should be able to terminate it if it started with /*=... >(ie =cut*/ becomes just */ ) > >b) any valid tag and not just 'pod' should be able to start it. Works for me. Keeper of the source format PDD? Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: PDD for code comments ????
At 10:30 AM 3/27/2001 +0100, Dave Mitchell wrote: > Dan Sugalski <[EMAIL PROTECTED]> wrote: > > At 02:58 PM 3/26/2001 +0100, Dave Mitchell wrote: > > >Nick Ing-Simmons <[EMAIL PROTECTED]> opined: > > > > Perhaps we could teach pod that /* was alias for =pod > > > > and */ an alias for =cut ? > > > > > >or possibly > > > > > >/*=foo is an alias for =foo, > > >and */ is an alias for =cut only after a /*= has been encountered. > > > > I think I'd rather we built a simple extractor rather than teach pod about > > how to extract itself from C comments, but if we're going to do that, tell > > it that */ is an alias for =cut, and that it should strip out leading > /* on > > lines... > >I'm happy think that we're using a special extractor rather than pod - >cf embed.pl producing perlapi.pod. However, I'd rather a plain ^/*...^*/ >not be picked up. Same here. All the C comments ought not be picked up. /*=pod and =cut*/ pairs aren't a bad thing to go with, though. Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: PDD for code comments ????
Dan Sugalski <[EMAIL PROTECTED]> wrote: > At 02:58 PM 3/26/2001 +0100, Dave Mitchell wrote: > >Nick Ing-Simmons <[EMAIL PROTECTED]> opined: > > > Perhaps we could teach pod that /* was alias for =pod > > > and */ an alias for =cut ? > > > >or possibly > > > >/*=foo is an alias for =foo, > >and */ is an alias for =cut only after a /*= has been encountered. > > I think I'd rather we built a simple extractor rather than teach pod about > how to extract itself from C comments, but if we're going to do that, tell > it that */ is an alias for =cut, and that it should strip out leading /* on > lines... I'm happy think that we're using a special extractor rather than pod - cf embed.pl producing perlapi.pod. However, I'd rather a plain ^/*...^*/ not be picked up.
Re: PDD for code comments ????
David L . Nicol <[EMAIL PROTECTED]> writes: >Nick Ing-Simmons wrote: > >> Perhaps we could teach pod that /* was alias for =pod >> and */ an alias for =cut ? > >that won't work because pod/cut is strictly line-based and C-style >comments are strictly stream-based. I was not suggesting we hunt down 2 ** /* */ 14 / /* */ 17 type comments I was just suggesting that pod could recognise line oriented block comments. /*=for ... */ vs /* =for ... =cut */ -- Nick Ing-Simmons
Re: PDD for code comments ????
On Mon, Mar 26, 2001 at 01:23:36PM -0600, David L. Nicol wrote: > Nick Ing-Simmons wrote: > > Perhaps we could teach pod that /* was alias for =pod > > and */ an alias for =cut ? > > that won't work because pod/cut is strictly line-based and C-style > comments are strictly stream-based. Damn. Could you patch embed.pl in the Perl 5 distribution, because it does more or less what Nick suggested perfectly well right now. :) -- "Having just ordered 40 books and discovered I have no change out of a grand, I'm thinking of getting a posse together and going after some publishers. I'd walk into a petrol station and buy lots of petrol on Monday, too, but I think I'd get funny looks. More funny looks." - Mark Dickerson
Re: PDD for code comments ????
Nick Ing-Simmons wrote: > Perhaps we could teach pod that /* was alias for =pod > and */ an alias for =cut ? that won't work because pod/cut is strictly line-based and C-style comments are strictly stream-based. -- David Nicol 816.235.1187 [EMAIL PROTECTED] He who says it's impossible shouldn't interrupt the one doing it.
Re: PDD for code comments ????
At 02:58 PM 3/26/2001 +0100, Dave Mitchell wrote: >Nick Ing-Simmons <[EMAIL PROTECTED]> opined: > > Perhaps we could teach pod that /* was alias for =pod > > and */ an alias for =cut ? > >or possibly > >/*=foo is an alias for =foo, >and */ is an alias for =cut only after a /*= has been encountered. I think I'd rather we built a simple extractor rather than teach pod about how to extract itself from C comments, but if we're going to do that, tell it that */ is an alias for =cut, and that it should strip out leading /* on lines... Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: PDD for code comments ????
Nick Ing-Simmons <[EMAIL PROTECTED]> opined: > >Either run pod through a pod puller before the C preprocessor gets to > >the code, or figure out a set of macros that can quote and ignore pod. > > > >The second is Yet Another Halting Problem so we go with the first? > > > >Which means a little program to depod the source before building it, > >or a -HASPOD extension to gcc > > > >Or just getting in the habit of writing > > > >/* > >=pod > > > > > >and > > > >=cut > >*/ > > Perhaps we could teach pod that /* was alias for =pod > and */ an alias for =cut ? or possibly /*=foo is an alias for =foo, and */ is an alias for =cut only after a /*= has been encountered. EG /*=for apidoc sv_upgrade Upgrade an SV to a more complex form. Use C. See C. */ rather than /* =for apidoc sv_upgrade Upgrade an SV to a more complex form. Use C. See C. =cut */
Re: PDD for code comments ????
David L . Nicol <[EMAIL PROTECTED]> writes: >Jarkko Hietaniemi wrote: > >> Some sort of simple markup embedded within the C comments. Hey, let's >> extend pod! Hey, let's use XML! Hey, let's use SGML! Hey, let's use >> XHTML! Hey, let's use lout! Hey, ... > >Either run pod through a pod puller before the C preprocessor gets to >the code, or figure out a set of macros that can quote and ignore pod. > >The second is Yet Another Halting Problem so we go with the first? > >Which means a little program to depod the source before building it, >or a -HASPOD extension to gcc > >Or just getting in the habit of writing > >/* >=pod > > >and > >=cut >*/ Perhaps we could teach pod that /* was alias for =pod and */ an alias for =cut ? -- Nick Ing-Simmons <[EMAIL PROTECTED]> Via, but not speaking for: Texas Instruments Ltd.
Re: PDD for code comments ????
Based on the silence == assent prinicple, I think we have agreed: 1. we need "a relatively strict and standard way" to document code. 2. This is the time and place to discuss it. 3. The result of the discusssion should be a PDD. 4. Most commentary should appear within the src file itself, or it's useless. 5. Broad agreement with my proposal for mandatory per file, per section, and per func/struct comments. 5a. Most of the structured comments should be extractable, even if we don't immediately make use of them. Obviously stuff that would be meaningless on its own shouldn't be extracted. Since this as all agreed, we can now move onto 6: > 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been > agreed? ie we thrash this bit out, then I'll write it up as an improved version of the PDD I scribbled earlier and submit it (now that I know how to submit PDDs :-) So here goes I want to combine: * "we need comments in the code" - me and a cast of thousands * "we need a commentary file per src file" RFC281 and Simon Cozens * "we need PDDs" - Dan and everyone into a 3-layer hierarchy. Take something like the IO system. At the top level, we have a PDD on IO saying [this example is totally fictional]: "we considered async, event, blah, etc but decided on async for the following reasons: blah blah. IO is be implemented by having a system-independent layer with the following API, and" ie a high-level document covering a whole subsystem. When people code up the IO subsystem, they will end up with a collection of src files, each implementing various aspects of it. Each (or most) src file has an associated (but separate) file providing an overall commentary for the code that is in the file. This describes low-level design decisons and histories for the things implemented in that file. Eg it might say: "We maintain a cache of IO handles, as it was found that this speeded up blah blah." Finally, there would be the individual comments within the source file. Here, a section comment would be more specific to the here-and now coding, eg "This section implements the IO handle cache. It is maintained as a doubley-linked list with IO_handle_root pointing to the head. pop_io_handle() grabs the most recent handle by simply yanking it from the head of the list, while push_io_handle() returns it to the head unless..." and the per-function comment for pop_io_handle() would say /* grab most recently used handle from the handle cache */ I would expect that the sort of level of information provided by something like perlguts.pod would naturally find its way spread between a PDD and commentary file, while the comments in the src file itself are at a lower level. ---|--- So, we need to decide whether we want a 3-level hierarchy like that suggested, and once agreed, the stucture and/or tagging of the commentary file and src comments.
Re: Tolkein (was Re: PDD for code comments ????)
Simply Hao wrote: > > Douglas Adams does seem rather more appropriate a source of quotes > > for software (anyone's, alas) than Pratchett. > > But Adams already has a software company. And Sirius pioneered the GPP in Perl 6.
Re: Tolkein (was Re: PDD for code comments ????)
> Douglas Adams does seem rather more appropriate a source of quotes > for software (anyone's, alas) than Pratchett. But Adams already has a software company. -Hao
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, 20 Feb 2001 19:17:25 + Simon Cozens <[EMAIL PROTECTED]> wrote: > On Tue, Feb 20, 2001 at 07:43:11PM +0100, H.Merijn Brand wrote: > > My name (Merijn) is *from* Tolkien's dutch translation, so I'm a little biases > > if I state: "Stick with Tolkien". Well, I'm of to Mordor now ... > > http://www.prembone.com/mythtakes/shiresong.html | Holy Mordor! I have been removed | I've been made a spectre, I don't know what to do | Distant island of Elvenkind | Brand of people who ain't my kind ^ | Holy Mordor! I have been removed See! They even use my surname! :-)) -- H.Merijn Brand using perl5.005.03 on HP-UX 10.20, HP-UX 11.00, AIX 4.2, AIX 4.3, DEC OSF/1 4.0 and WinNT 4.0 SP-6a, often with Tk800.020 and/or DBD-Unify ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/H/HM/HMBRAND/ Member of Amsterdam Perl Mongers (http://www.amsterdam.pm.org/)
Re: PDD for code comments ????
David Mitchell wrote: > 4. Are we all agreed that in addition to anything else (eg rfc281), at > least some of the standard commentary should appear actually within the > src file itself? s/at least some/most, if not all/ > 5. Do *all* these comments need to be extractable, or only ones related > to published APIs etc? Initially the automaton creates them all extractable, and the coder can depod the ones that are implementation details and should not be published, as a measure more extreme than noting "This function is an implementaion detail" in the mandatory comment for the function. Which implies an at least implicit standard lexicon of flexibility to use in these comments, ranging from "implements ISO standard interface" down to "experimental - failed, remove during clean-up phase" > 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been > agreed? I can't. Can you? Altering a C prettyprinter to insert an extensible standard comment template before each function definition would be even easier than writing one from scratch. But what goes in that block of text, beyond /* =pod =head1 function $FunctionName returning $ReturnType =head1 Named arguments: @ArgNameList =cut */
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, Feb 20, 2001 at 07:43:11PM +0100, H.Merijn Brand wrote: > My name (Merijn) is *from* Tolkien's dutch translation, so I'm a little biases > if I state: "Stick with Tolkien". Well, I'm of to Mordor now ... http://www.prembone.com/mythtakes/shiresong.html -- "It's God. No, not Richard Stallman, or Linus Torvalds, but God." (By Matt Welsh)
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, 20 Feb 2001 18:18:31 + Nicholas Clark <[EMAIL PROTECTED]> wrote: > On Tue, Feb 20, 2001 at 06:06:49PM +, David Mitchell wrote: > > > > And what about us poor semi-literates who've never heard of Yojimbo ??? > > > > If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s > > > > read him :-) > > > > > > Adams rather than Pratchett, I'd think. :) > > > > But Pratchet has 20+ books to his credit, so we need never run out of quotes > > :-) > > As long as Terry Pratchett writes books faster than perl consumes quotes. > Based on the fact that he's still very alive, we aren't in danger yet. > > However, Larry has already commented on the danger of running out of LOTR > quotes: > > http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-02/msg00369.html My name (Merijn) is *from* Tolkien's dutch translation, so I'm a little biases if I state: "Stick with Tolkien". Well, I'm of to Mordor now ... -- H.Merijn Brand using perl5.005.03 on HP-UX 10.20, HP-UX 11.00, AIX 4.2, AIX 4.3, DEC OSF/1 4.0 and WinNT 4.0 SP-6a, often with Tk800.020 and/or DBD-Unify ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/H/HM/HMBRAND/ Member of Amsterdam Perl Mongers (http://www.amsterdam.pm.org/)
Re: Tolkein (was Re: PDD for code comments ????)
At 06:18 PM 02-20-2001 +, Nicholas Clark wrote: >As long as Terry Pratchett writes books faster than perl consumes quotes. >Based on the fact that he's still very alive, we aren't in danger yet. True... And he has some very good quotes. >However, Larry has already commented on the danger of running out of LOTR >quotes: > >http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-02/msg00369.html That thread does raise another concern in my mind. While a quote here and a quote there would constitute "Fair Use", if we are seriously in danger of running out of quotes, we are pushing the bounds of "Fair Use". I think, for copyright considerations alone, it's worth expanding to other authors. "Literate Programming"? Well, the Perl source is well read... >Nicholas Clark
Re: Tolkein (was Re: PDD for code comments ????)
At 07:52 PM 2/20/2001 +0200, Roman M. Parparov wrote: >On Tue, Feb 20, 2001 at 05:57:10PM +, David Mitchell wrote: > > > Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to > > > put together a list of good ones? It's been ages since I've read the > books, > > > and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo > > > strikes me as a good place to yank from, as does Zot!, but Pratchett > will > > > do too...) > > > > Err, would that be Larry's prerogative ??? > > > > And what about us poor semi-literates who've never heard of Yojimbo ??? > > If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s > > read him :-) > >Adams rather than Pratchett, I'd think. :) Douglas Adams does seem rather more appropriate a source of quotes for software (anyone's, alas) than Pratchett. Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: Tolkein (was Re: PDD for code comments ????)
At 05:57 PM 2/20/2001 +, David Mitchell wrote: > > Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to > > put together a list of good ones? It's been ages since I've read the > books, > > and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo > > strikes me as a good place to yank from, as does Zot!, but Pratchett will > > do too...) > >Err, would that be Larry's prerogative ??? Yep, it would. Hence the call for a list of quotes from LOTR. :) >And what about us poor semi-literates who've never heard of Yojimbo ??? >If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s >read him :-) Sheesh, kids today. You can't even count on anyone having a misspent youth anymore... Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, Feb 20, 2001 at 06:06:49PM +, David Mitchell wrote: > > > And what about us poor semi-literates who've never heard of Yojimbo ??? > > > If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s > > > read him :-) > > > > Adams rather than Pratchett, I'd think. :) > > But Pratchet has 20+ books to his credit, so we need never run out of quotes > :-) As long as Terry Pratchett writes books faster than perl consumes quotes. Based on the fact that he's still very alive, we aren't in danger yet. However, Larry has already commented on the danger of running out of LOTR quotes: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-02/msg00369.html Nicholas Clark
Re: Tolkein (was Re: PDD for code comments ????)
> > And what about us poor semi-literates who've never heard of Yojimbo ??? > > If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s > > read him :-) > > Adams rather than Pratchett, I'd think. :) But Pratchet has 20+ books to his credit, so we need never run out of quotes :-)
Re: Tolkein (was Re: PDD for code comments ????)
> Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to > put together a list of good ones? It's been ages since I've read the books, > and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo > strikes me as a good place to yank from, as does Zot!, but Pratchett will > do too...) Err, would that be Larry's prerogative ??? And what about us poor semi-literates who've never heard of Yojimbo ??? If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s read him :-)
Re: Tolkein (was Re: PDD for code comments ????)
On Tue, Feb 20, 2001 at 05:57:10PM +, David Mitchell wrote: > > Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to > > put together a list of good ones? It's been ages since I've read the books, > > and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo > > strikes me as a good place to yank from, as does Zot!, but Pratchett will > > do too...) > > Err, would that be Larry's prerogative ??? > > And what about us poor semi-literates who've never heard of Yojimbo ??? > If we can't go with Tolkien, I'd vote for Pratchett, 'cause *everyone*'s > read him :-) Adams rather than Pratchett, I'd think. :) -- Roman M. Parparov - NASA EOSDIS project node at TAU technical manager. Email: [EMAIL PROTECTED] http://www.komkon.org/~romm Phone/Fax: +972-(0)3-6405205 (work), +972-(0)54-629-884 (home) -- The economy depends about as much on economists as the weather does on weather forecasters. -- Jean-Paul Kauffmann
Re: Tolkein (was Re: PDD for code comments ????)
At 04:50 PM 2/20/2001 +, David Mitchell wrote: > > Tolkien quotes are mandatory? > > > > perl5's globals.c malloc.c perlio.c perly.c universal.c xsutils.c > > definitely fail then. > >Sounds like some urgent patches need submitting to p5p ;-) Do we want to go with Tolkein quotes for perl 6 and, if so, who wants to put together a list of good ones? It's been ages since I've read the books, and I'm likely to pull quotes from other places anyway. (Usagi Yojimbo strikes me as a good place to yank from, as does Zot!, but Pratchett will do too...) Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Tolkein (was Re: PDD for code comments ????)
> Tolkien quotes are mandatory? > > perl5's globals.c malloc.c perlio.c perly.c universal.c xsutils.c > definitely fail then. Sounds like some urgent patches need submitting to p5p ;-)
Re: PDD for code comments ????
On Tuesday 20 February 2001 10:49, David Mitchell wrote: > Regarding comments in code: > 2. Is this the time and place to discuss it? Certainly before we actually begin coding > > 3. Should the result of the discusssion be a PDD? Yes. > > 5. Do *all* these comments need to be extractable, or only ones related > to published APIs etc? All extractable comments need to be extractable, which doesn't make sense, I know. There are two, maybe three different kinds of comments - metadata type comments (like which API is belongs to, versioning, authorship, etc), explanatory ( /* one little, two little, three little endians */ ), and completely unnecessary ( /* Twas brillig... */ and most prologues ) The first, certainly, whether we plan to extract them now or not. The second, of course not, they are meaningless without the code. They're often meaningless *with* the code. The third, maybe, if only for trivialness. :-) > > 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been > agreed? Good idea. Define the why, the what, and then the how. -- Bryan C. Warnock [EMAIL PROTECTED]
Re: PDD for code comments ????
On Tue, Feb 20, 2001 at 03:49:44PM +, David Mitchell wrote: > 4. Are we all agreed that in addition to anything else (eg rfc281), at > least some of the standard commentary should appear actually within the > src file itself? quote from someone recently "separate documentation is no documentation" (sorry, forget who) which seemed a nice way of describing it. I think it would be good to make it so easy to documented code as you write it that there really would be no excuse not to do it > 5. Does anyone agree or disagree with my proposal for mandatory > per file, per section, and per func/struct comments? Tolkien quotes are mandatory? perl5's globals.c malloc.c perlio.c perly.c universal.c xsutils.c definitely fail then. [globals.c malloc.c miniperlmain.c perly.c regcomp.c regexp.c taint.c universal.c xsutils.c have no copyright statement.] embed.pl doesn't add a Tolkien quote or a copyright statement to perl API.c > 5. Do *all* these comments need to be extractable, or only ones related > to published APIs etc? You have 2 point 5s. [I feel there must be a Monty Python quote related to this, but apart from "Rule 6 - there is /no/ rule six" from the Bruces sketch, I'm lost] It would be good to be able to extract documentation relating to the implementation behind the APIs, for guts hackers. > PS. I decree that this email solves Warnock's Dilemma [*] by assuming > that silence implies absolute assent to everything I have ever said or > will ever say. ;-) I don't think "will ever say" holds. And I think I'd phrase it as "ongoing silence". But apart from that, it seems to be a working assumption for design proposals. Nicholas Clark
Re: PDD for code comments ????
Regarding comments in code: Chopping and misquoting wildly Jarkko Hietaniemi said: * I would define a relatively strict and standard way to do this so that the documentation can be extracted out. * lets avoid a markup-up flamewar Simon Cozens said: * I'd like to see Perl 6 written as a literate program * the apidoc is a really good thing, but it needs to be made more extensible * RFC281 was an initial set of thoughts on this idea. David L. Nicol said: /* =pod =cut */ Whereas I'm about to say Questions: 1. Does anyone *disagree* that we need "a relatively strict and standard way" to document code? 2. Is this the time and place to discuss it? 3. Should the result of the discusssion be a PDD? 4. Are we all agreed that in addition to anything else (eg rfc281), at least some of the standard commentary should appear actually within the src file itself? 5. Does anyone agree or disagree with my proposal for mandatory per file, per section, and per func/struct comments? 5. Do *all* these comments need to be extractable, or only ones related to published APIs etc? 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been agreed? 7. What is the average air speed velocity of a swallow, etc etc... Dave M. PS. I decree that this email solves Warnock's Dilemma [*] by assuming that silence implies absolute assent to everything I have ever said or will ever say. ;-) [*] Or should that be quintlemma, or pentlemma, or ? Any Classics scholars out there?
Re: PDD for code comments ????
Jarkko Hietaniemi wrote: > Some sort of simple markup embedded within the C comments. Hey, let's > extend pod! Hey, let's use XML! Hey, let's use SGML! Hey, let's use > XHTML! Hey, let's use lout! Hey, ... Either run pod through a pod puller before the C preprocessor gets to the code, or figure out a set of macros that can quote and ignore pod. The second is Yet Another Halting Problem so we go with the first? Which means a little program to depod the source before building it, or a -HASPOD extension to gcc Or just getting in the habit of writing /* =pod and =cut */ -- David Nicol 816.235.1187 [EMAIL PROTECTED] "Nothing in the definition of the word `word' says that a word has to be in a dictionary to be called one." -- Anu Garg
Re: PDD for code comments ????
On Mon, Feb 19, 2001 at 03:13:02PM +, Simon Cozens wrote: > On Mon, Feb 19, 2001 at 08:37:48AM -0600, Jarkko Hietaniemi wrote: > > Hey, let's extend pod! Hey, let's use XML! Hey, let's use SGML! Hey, > > let's use XHTML! Hey, let's use lout! Hey, ... > > Can we take this to perl6-trivial-flamewars-markup-language, please? :) I just tried to preempt the whole war -- "My markup is bigger than you markup, so there." -- $jhi++; # http://www.iki.fi/jhi/ # There is this special biologist word we use for 'stable'. # It is 'dead'. -- Jack Cohen
Re: PDD for code comments ????
On Mon, Feb 19, 2001 at 08:37:48AM -0600, Jarkko Hietaniemi wrote: > Hey, let's extend pod! Hey, let's use XML! Hey, let's use SGML! Hey, > let's use XHTML! Hey, let's use lout! Hey, ... Can we take this to perl6-trivial-flamewars-markup-language, please? :) -- "He was a modest, good-humored boy. It was Oxford that made him insufferable."
Re: PDD for code comments ????
On Mon, Feb 19, 2001 at 02:27:06PM +, Simon Cozens wrote: > On Mon, Feb 19, 2001 at 08:17:17AM -0600, Jarkko Hietaniemi wrote: > > I would define a relatively strict and standard way to do this so that > > the documentation can be extracted out. > > I'd like to see Perl 6 written as a literate program, but that's probably > the axe I need to grind. :) Seriously, the apidoc is a really good thing, > but it needs to be made more extensible; at the moment it only really works > for documenting functions. I think we'll need a more general "structural" > documentation on the source; RFC281 was an initial set of thoughts on this Some sort of simple markup embedded within the C comments. Hey, let's extend pod! Hey, let's use XML! Hey, let's use SGML! Hey, let's use XHTML! Hey, let's use lout! Hey, ... -- $jhi++; # http://www.iki.fi/jhi/ # There is this special biologist word we use for 'stable'. # It is 'dead'. -- Jack Cohen
Re: PDD for code comments ????
On Mon, Feb 19, 2001 at 08:17:17AM -0600, Jarkko Hietaniemi wrote: > I would define a relatively strict and standard way to do this so that > the documentation can be extracted out. I'd like to see Perl 6 written as a literate program, but that's probably the axe I need to grind. :) Seriously, the apidoc is a really good thing, but it needs to be made more extensible; at the moment it only really works for documenting functions. I think we'll need a more general "structural" documentation on the source; RFC281 was an initial set of thoughts on this idea. > A related matter is that currently we have a central .pl file that is > used to generate the appropriate prototype headers and various cpp > magic incantations e.g. creating the threaded versions. I find this > to be curious direction: I would expect the .c files to be the master > files for function signatures, from which the prototype headers are > generated. If we're dealing with, say, vtable functions, I think we'll need to generate a lot of information from the function signature itself; see the dummy vtable generation code I posted the other day. (Incidentally, I recently modified that so that you can put POD in the vtable source. :) -- Morton's Law: If rats are experimented upon, they will develop cancer.
Re: PDD for code comments ????
Not a joke, I find this to be a very valuable rule. No comments, no check-ins. I would define a relatively strict and standard way to do this so that the documentation can be extracted out. References: see perlapi and perlintern in the current development releases. A related matter is that currently we have a central .pl file that is used to generate the appropriate prototype headers and various cpp magic incantations e.g. creating the threaded versions. I find this to be curious direction: I would expect the .c files to be the master files for function signatures, from which the prototype headers are generated. -- $jhi++; # http://www.iki.fi/jhi/ # There is this special biologist word we use for 'stable'. # It is 'dead'. -- Jack Cohen
PDD for code comments ????
I originally starting writing this as a bit of a joke, then I thought
perhaps I should submit it as a serious suggestion. Anyone violently
against or in favour? Is this even an issue that should go in a PDD?
Does anyone care? Should I return to my box now?
Dave M.
=head1 TITLE
Mandatory comments within Perl source code
=head1 VERSION
=head2 CURRENT
Maintainer: Dave Mitchell <[EMAIL PROTECTED]>
Class: Internals
PDD Number: TBD
Version: 1
Status: Proposed
Last Modified: 17 February 2001
PDD Format: 1
Language: English
=head2 HISTORY
None. First version
=head1 CHANGES
None. First version
=head1 ABSTRACT
This RFC describes the minimum set of comments that B be present in
every source file.
=head1 DESCRIPTION
One of the criticisms of Perl 5 is that it's source code is impenetrable
to newcomers, not least because of the lack often of comments within
the code. This document provides some minimum standards for adding
commentary to source files; code which does not follow these guidelines
should not be accepted into the main code stream(s).
Of course, you are allowed to add comments in addition to the ones
mandated here :-)
=head1 IMPLEMENTATION
=head2 Per-file comments
In addition to the copyright message and LOTR quote, each file should
have a comment at the top explaining the basic purpose of the file, eg
/* pp_hot.c - like pp.c, this file contains functions that operate
* on the contents of the stack (pp == 'push & pop'), but in this
* case, frequently used ('hot') functions have been moved here
* from pp.c to (hopefully) improve CPU cache hit rates.
*/
=head2 Per-section comments
If there is a collection of functions, structures or whatever which
are grouped together and have a common theme or purpose, there should
be a general comment at the start of the section explaining their overall
purpose. (If there is only one section, then the per-file comment
already satisfies this requirement.)
/* This section deals with 'arenas', which are chunks of SVs of
* a particular type that are allocated in one go. Individual
* requests can then be made to grab or release individual SVs.
* For each type I, there is a global pointer called
* I which blah blah
*/
=head2 Per-function and per-structure comments
Each function and structure should have at least a short one-line
comment explaining its purpose. Often this will be be little more than
expanding the acronym making up the function's name, with the wider
purpose already explained by the section comment; but sometimes more
explanation will be needed.
/* return an Integer SV to its arena */
STATIC void
S_del_xiv(pTHX_ XPVIV *p)
...
=head2 Optimisations
Any code which is deliberately written in a strange way to make it run
faster should be flagged as such, in order to stop some shmuck trying
subsequently to replace it with something 'cleaner'.
/* NB - this may look bizarre, but partial unrolling of the
* loop makes the hash calculation a lot faster, at the expense
* of slightly larger code. See http// for the full gory details.
*/
=head1 REFERENCES
The Perl 5 source :-)
