Everything
php
Learn Community Releases The PHP Project
Home » Project » Newsgroups » php.internals » Doc comment patch »

Doc comment patch

php.internals

Andrei Zmievski

23 years ago
Pursuant to the introspection portion of TODO-PHP5, here is a small patch that: - Keeps track of starting/ending line numbers for user functions. - Removes extraneous T_ML_COMMENT token. - Stores the last seen doc comment (JavaDoc style) in the compiler globals for future access by the introspection features and introduces the new T_DOC_COMMENT token. The doc comment is defined as a multiline comment starting with "/** \n" and ending with "*/". So, in the following example: /** * @name foo * @param blah string */ function foo($blah) { } The CG(doc_comment) will contain: * @name foo * @param blah string What is left to do here is adding the T_DOC_COMMENT to parser rules and storing it in the appropriate structures (zend_op_array for functions, zend_class_entry for classes, etc). If no one objects, I will commit it shortly. -Andrei http://www.gravitonic.com/ The Feynman problem solving algorithm: 1) Write down the problem. 2) Think real hard. 3) Write down the answer.

Andrei Zmievski

23 years ago
I will remember to attach the patch... I will remember to attach the patch... I will remember to attach the patch... I will.. On Thu, 13 Mar 2003, Andrei Zmievski wrote:
> Pursuant to the introspection portion of TODO-PHP5, here is a small > patch that:
-Andrei http://www.gravitonic.com/ "When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute, and it's longer than any hour. That's relativity." -- Einstein, on relativity

(Marcus Börger)

23 years ago
At 21:51 13.03.2003, Andrei Zmievski wrote:
>Pursuant to the introspection portion of TODO-PHP5, here is a small >patch that: > >- Keeps track of starting/ending line numbers for user functions. >- Removes extraneous T_ML_COMMENT token. >- Stores the last seen doc comment (JavaDoc style) in the compiler > globals for future access by the introspection features and introduces > the new T_DOC_COMMENT token. The doc comment is defined as a multiline > comment starting with "/** \n" and ending with "*/". So, in the > following example: > >/** > * @name foo > * @param blah string > */ >function foo($blah) >{ >} > >The CG(doc_comment) will contain: > * @name foo > * @param blah string > >What is left to do here is adding the T_DOC_COMMENT to parser rules and >storing it in the appropriate structures (zend_op_array for functions, >zend_class_entry for classes, etc). > >If no one objects, I will commit it shortly.
Great! Some questions: 1) Will you allow compatibility with doxygen by this: +<ST_IN_SCRIPTING>"/** "{NEWLINE} { + CG(comment_start_line) = CG(zend_lineno); + BEGIN(ST_DOC_COMMENT); + yymore(); +} + changed to: +<ST_IN_SCRIPTING>("/** "|"/*! "){NEWLINE} { + CG(comment_start_line) = CG(zend_lineno); + BEGIN(ST_DOC_COMMENT); + yymore(); +} + 2) Why is it '/' '*' '*' and SPACE? 3) How about single line comments started by '//!'? 4) What about removing everything upto '*' if it is the first character after a new line starts? regards marcus

Andrei Zmievski

23 years ago
On Thu, 13 Mar 2003, Marcus Börger wrote:
> Great! > > Some questions: > > 1) Will you allow compatibility with doxygen by this: > > +<ST_IN_SCRIPTING>"/** "{NEWLINE} { > + CG(comment_start_line) = CG(zend_lineno); > + BEGIN(ST_DOC_COMMENT); > + yymore(); > +} > + > > changed to: > +<ST_IN_SCRIPTING>("/** "|"/*! "){NEWLINE} { > + CG(comment_start_line) = CG(zend_lineno); > + BEGIN(ST_DOC_COMMENT); > + yymore(); > +} > +
When Stig and I discussed this feature, I was under the impression that it would be used in PEAR mostly, and that PEAR would adhere to JavaDoc-style comments. Is there enough demand for doxygen comments?
> 2) Why is it '/' '*' '*' and SPACE?
That's what Stig told me to use. :) Stig?
> 3) How about single line comments started by '//!'?
I think Doc comments should be multi-line.
> 4) What about removing everything upto '*' if it is the first character > after a new line starts?
It's a possibility. You basically want to strip the example that I gave down to this?: @name foo @param blah string -Andrei http://www.gravitonic.com/ * Use the source, Luke. *

(Marcus Börger)

23 years ago
> > 4) What about removing everything upto '*' if it is the first character > > after a new line starts? > >It's a possibility. You basically want to strip the example that I gave >down to this?: > >@name foo >@param blah string
Yes, sure :-)

Andrei Zmievski

23 years ago
On Thu, 13 Mar 2003, Marcus Börger wrote:
> >It's a possibility. You basically want to strip the example that I gave > >down to this?: > > > >@name foo > >@param blah string > > Yes, sure :-)
I could put the code to strip those out in the scanner, but it would slow things down. If it's acceptable to have just the body of doc comment minus the comment leader and trailer, then I'd rather do that. -Andrei http://www.gravitonic.com/ "When I get a little money, I buy books; and if any is left I buy food and clothes." -- Erasmus

(Marcus Börger)

23 years ago
At 22:49 13.03.2003, Andrei Zmievski wrote:
>On Thu, 13 Mar 2003, Marcus Börger wrote: > > >It's a possibility. You basically want to strip the example that I gave > > >down to this?: > > > > > >@name foo > > >@param blah string > > > > Yes, sure :-) > >I could put the code to strip those out in the scanner, but it would >slow things down. If it's acceptable to have just the body of doc >comment minus the comment leader and trailer, then I'd rather do that.
I think this is the way to go. A potential extension using the doc info will take care about it. marcus

(Marcus Börger)

23 years ago
At 22:05 13.03.2003, Andrei Zmievski wrote:
> > 4) What about removing everything upto '*' if it is the first character > > after a new line starts? > >It's a possibility. You basically want to strip the example that I gave >down to this?: > >@name foo >@param blah string
<ST_DOC_SCRIPTING>{NEWLINE}{TABS_AND_SPACES}"*" { yymore(); } should do the trick.... marcus

Andrei Zmievski

23 years ago
On Thu, 13 Mar 2003, Marcus Börger wrote:
> <ST_DOC_SCRIPTING>{NEWLINE}{TABS_AND_SPACES}"*" { > yymore(); > } > > should do the trick....
You mean <ST_DOC_COMMENT>^{TABS_AND_SPACES}"*" /* eat up */? Wouldn't work. -Andrei http://www.gravitonic.com/ "The most exciting phrase to hear in science, the one that heralds new discoveries, is not "Eureka!" but "That's funny..." -- Isaac Asimov.

(Marcus Börger)

23 years ago
At 22:05 13.03.2003, Andrei Zmievski wrote:
> > 2) Why is it '/' '*' '*' and SPACE? > >That's what Stig told me to use. :) Stig?
A single space at the end of a line is nothing that helps in a syntax it makes things only hard to understand and ensures that you make a lot of mistakes. marcus

Andrei Zmievski

23 years ago
On Thu, 13 Mar 2003, Marcus Börger wrote:
> >That's what Stig told me to use. :) Stig? > > A single space at the end of a line is nothing that helps in a > syntax it makes things only hard to understand and ensures > that you make a lot of mistakes.
Well, as long as we don't confuse doc comments with regular ones.. -Andrei http://www.gravitonic.com/ For every complex problem, there is a solution that is simple, neat, and wrong. -- H. L. Mencken

Andi Gutmans

23 years ago
Hmm. I thought introspection is reflection. It seems I misunderstood. Are you sure it's worth bloating the engine to hold this extra information? Andi At 03:51 PM 3/13/2003 -0500, Andrei Zmievski wrote:

Andrei Zmievski

23 years ago
On Fri, 14 Mar 2003, Andi Gutmans wrote:
> Hmm. I thought introspection is reflection. It seems I misunderstood.
I think that introspection is a superset of reflection.
> Are you sure it's worth bloating the engine to hold this extra information?
It is possible that an extension or a PEAR class could parse through the file and extract the doc comments, but since the engine is already doing the scanning/parsing, I thought it might be very convenient to use it. Yes, the structure will need to have extra fields, but how much bloat are we talking about? And if the reflection is to be good, it _will_ need additional information from the engine, such as the function parameter names, class type hints, etc - all this needs to be stored somewhere and it can't be an extension since it can't hook into the scanning/compilation process. If you don't like this approach, I am open to ideas. -Andrei http://www.gravitonic.com/ "The time from now until the completion of the project tends to become constant." -- Douglas Hartree

Andi Gutmans

23 years ago
At 09:05 AM 3/14/2003 -0500, Andrei Zmievski wrote:
>On Fri, 14 Mar 2003, Andi Gutmans wrote: > > Hmm. I thought introspection is reflection. It seems I misunderstood. > >I think that introspection is a superset of reflection. > > Are you sure it's worth bloating the engine to hold this extra information? > >It is possible that an extension or a PEAR class could parse through the >file and extract the doc comments, but since the engine is already doing >the scanning/parsing, I thought it might be very convenient to use it. >Yes, the structure will need to have extra fields, but how much bloat >are we talking about? And if the reflection is to be good, it _will_ >need additional information from the engine, such as the function >parameter names, class type hints, etc - all this needs to be stored >somewhere and it can't be an extension since it can't hook into the >scanning/compilation process. > >If you don't like this approach, I am open to ideas.
Let's see what the API for reflection will look like and then discuss the information we need. Andi

Andrei Zmievski

23 years ago
On Fri, 14 Mar 2003, Andi Gutmans wrote:
> Let's see what the API for reflection will look like and then discuss the > information we need.
Okay. -Andrei http://www.gravitonic.com/ * George Orwell was an optimist. *