By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
432,009 Members | 1,487 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 432,009 IT Pros & Developers. It's quick & easy.

Is phpdoc block boundary syntax strict?

pbmods
Expert 5K+
P: 5,821
Nobody I know actually uses phpdoc, but some of the staff where I work use IDEs that can parse phpdoc blocks, so I try to be accommodating. Plus I might just use it someday if I have some time to kill. In the meantime...

I'm curious if phpdoc block boundaries are 'strict'. In other words, I've only ever heard of phpdoc blocks formatted like this:

Expand|Select|Wrap|Line Numbers
  1. /**
  2. *
  3. * ... doc content goes here ...
  4. *
  5. */
  6.  
But what if I did this:

Expand|Select|Wrap|Line Numbers
  1. /****************
  2. **
  3. **    ... more doc content ...
  4. */
  5.  
Or this:

Expand|Select|Wrap|Line Numbers
  1. /****************
  2. //
  3. //    ... and so forth ...
  4. */
  5.  
Each comment block style has a specific meaning in my code, so I don't really want to cramp my style to make phpdoc happy.

Thanks for your time.
May 15 '07 #1
Share this Question
Share on Google+
3 Replies


Motoma
Expert 2.5K+
P: 3,235
I am not sure about how strict phpdoc is, however, I do know that the Zend IDE uses phpdoc to give function descriptions and mouseover hints. What you might want to try is downloading the free trial of Zend, and loading up one of your scripts. Then, begin typing the name of a function, and when you get the pop-up, see if everything is displayed correctly. Your other option is to sift through the phpdoc documentation (boy there better be some), or send them a friendly email.

Nobody I know actually uses phpdoc, but some of the staff where I work use IDEs that can parse phpdoc blocks, so I try to be accommodating. Plus I might just use it someday if I have some time to kill. In the meantime...

I'm curious if phpdoc block boundaries are 'strict'. In other words, I've only ever heard of phpdoc blocks formatted like this:

Expand|Select|Wrap|Line Numbers
  1. /**
  2. *
  3. * ... doc content goes here ...
  4. *
  5. */
  6.  
But what if I did this:

Expand|Select|Wrap|Line Numbers
  1. /****************
  2. **
  3. **    ... more doc content ...
  4. */
  5.  
Or this:

Expand|Select|Wrap|Line Numbers
  1. /****************
  2. //
  3. //    ... and so forth ...
  4. */
  5.  
Each comment block style has a specific meaning in my code, so I don't really want to cramp my style to make phpdoc happy.

Thanks for your time.
May 15 '07 #2

pbmods
Expert 5K+
P: 5,821
After sifting a little deeper through phpdoc's documentation (indeed!), I came across this:

Any line within a DocBlock that doesn't begin with a * will be ignored.
Ok. So that's half of it.

And here's the line above it:

A DocBlock is an extended C++-style PHP comment that begins with "/**" and has an "*" at the beginning of every line. DocBlocks precede the element they are documenting.
Though it didn't specifically say otherwise, my guess is that if I wanted phpdoc functionality, I'd be stuck with the standard phpdoc format. Phoo.

Although it looks like I could make the last line any format that I wanted :P

Expand|Select|Wrap|Line Numbers
  1. /**
  2. *
  3. *    A beautiful, relaxing sunset.
  4. *
  5. *    You are on a warm, sandy beach.  The sky is turning a most absolutely
  6. *        gorgeous shade of purple as the sun slowly sinks into the horizon across
  7. *        the crashing waves.
  8. *
  9. *    You see a note.
  10. *
  11. *    @exits north, south
  12. *
  13.  
  14.             ^^                   @@@@@@@@@
  15.        ^^       ^^            @@@@@@@@@@@@@@@
  16.                             @@@@@@@@@@@@@@@@@@              ^^
  17.                            @@@@@@@@@@@@@@@@@@@@
  18.  ~~~~ ~~ ~~~~~ ~~~~~~~~ ~~ &&&&&&&&&&&&&&&&&&&& ~~~~~~~ ~~~~~~~~~~~ ~~~
  19.  ~         ~~   ~  ~       ~~~~~~~~~~~~~~~~~~~~ ~       ~~     ~~ ~
  20.    ~      ~~      ~~ ~~ ~~  ~~~~~~~~~~~~~ ~~~~  ~     ~~~    ~ ~~~  ~ ~~
  21.    ~  ~~     ~         ~      ~~~~~~  ~~ ~~~       ~~ ~ ~~  ~~ ~
  22.  ~  ~       ~ ~      ~           ~~ ~~~~~~  ~      ~~  ~             ~~
  23.        ~             ~        ~      ~      ~~   ~             ~
  24. */
  25.  
[EDIT: ASCII art borrowed from chris.com]
May 16 '07 #3

Motoma
Expert 2.5K+
P: 3,235
Although it looks like I could make the last line any format that I wanted :P

Expand|Select|Wrap|Line Numbers
  1. /**
  2. *
  3. *    A beautiful, relaxing sunset.
  4. *
  5. *    You are on a warm, sandy beach.  The sky is turning a most absolutely
  6. *        gorgeous shade of purple as the sun slowly sinks into the horizon across
  7. *        the crashing waves.
  8. *
  9. *    You see a note.
  10. *
  11. *    @exits north, south
  12. *
  13.  
  14.             ^^                   @@@@@@@@@
  15.        ^^       ^^            @@@@@@@@@@@@@@@
  16.                             @@@@@@@@@@@@@@@@@@              ^^
  17.                            @@@@@@@@@@@@@@@@@@@@
  18.  ~~~~ ~~ ~~~~~ ~~~~~~~~ ~~ &&&&&&&&&&&&&&&&&&&& ~~~~~~~ ~~~~~~~~~~~ ~~~
  19.  ~         ~~   ~  ~       ~~~~~~~~~~~~~~~~~~~~ ~       ~~     ~~ ~
  20.    ~      ~~      ~~ ~~ ~~  ~~~~~~~~~~~~~ ~~~~  ~     ~~~    ~ ~~~  ~ ~~
  21.    ~  ~~     ~         ~      ~~~~~~  ~~ ~~~       ~~ ~ ~~  ~~ ~
  22.  ~  ~       ~ ~      ~           ~~ ~~~~~~  ~      ~~  ~             ~~
  23.        ~             ~        ~      ~      ~~   ~             ~
  24. */
  25.  
[EDIT: ASCII art borrowed from chris.com]
I would be offended if you didn't!!

P.S. MUD references make me warm and tingly.
May 16 '07 #4

Post your reply

Sign in to post your reply or Sign up for a free account.