# Doc comment patch

- Thread: https://externals.io/message/31
- Original archive: https://news-web.php.net/php.internals/31
- Started by Andrei Zmievski on 2003-03-13T20:51:23+00:00
- Messages: 6
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #31 — Andrei Zmievski — 2003-03-13T20:51:23+00:00

URL: https://externals.io/message/31#31

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.

---

## #32 — Andrei Zmievski — 2003-03-13T20:52:41+00:00

URL: https://externals.io/message/31#32 · In reply to: #31

I will remember to attach the patch...
I will remember to attach the patch...
I will remember to attach the patch...
I will..


> 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

---

## #33 — marcus.boerger@t-online.de — 2003-03-13T21:01:50+00:00

URL: https://externals.io/message/31#33 · In reply to: #31

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

---

## #34 — Andrei Zmievski — 2003-03-13T21:05:28+00:00

URL: https://externals.io/message/31#34 · In reply to: #33

> 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. *

---

## #43 — Andi Gutmans — 2003-03-14T12:28:52+00:00

URL: https://externals.io/message/31#43 · In reply to: #31

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:
>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.

---

## #47 — Andrei Zmievski — 2003-03-14T14:05:07+00:00

URL: https://externals.io/message/31#47 · In reply to: #43

> 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