Tanton Gibbs wrote: >I agree with this; however, I also think it would be nice to have it all in >one place. It's a nuisance to have to open every file just to see what it >is. By the time I figure out what the 60th file does, I've forgotten what >the first does. It would be nice to have the information at the top of the >file >and then have a program pull it and create a separate file...that way they >are always in sync. > > Hi, I agree with you completely. I like embedded documents. I would like to see the docs/dev directory filled up with generated documentation as part of the build process. I wrote the parrotdoc thing to quickly get something that will work in C and in Perl and look like it was a comment. While trying to figure out what the various files,structs, and functions do in parrot, I was commenting the code. I wanted a way to autogenerate documents with these comments. But The consensus was to use POD to do the embedded document thing. I decided not to continue on the "comment the code route" because I don't like POD. And I think a good demonstration of why I don't like it is the ops files. I am trying to think of a polite way to introduce java and python people to the ops files when they are a mixture of C, POD and perl comments. I would hate to see all the C files go this route. It will make it unreadable to anyone that does not use POD.
If parrot decides to go the route of embedding documents in its C code. Please do not use POD! Find a C developer sitting next to you that does not know POD and ask them how they like the flow of the ops files. Someone suggested 'doxygen', I am sure there are several other document/comment styles out there. Tanton Gibbs himself wrote: "I personally find POD distasteful, but since it is the norm, then I think we should stick with it." POD is not the norm in C, and Parrot can't be stuck in a rut already. Sorry for the rant, Erik
