473,320 Members | 1,926 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,320 software developers and data experts.

Is phpdoc block boundary syntax strict?

pbmods
5,821 Expert 4TB
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
3 1690
Motoma
3,237 Expert 2GB
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
5,821 Expert 4TB
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
3,237 Expert 2GB
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

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

Similar topics

5
by: point | last post by:
Anyone knows of a good and easy program or script which generates doc file from a phpdoc style comments???? PhpEdit has something like that but I need a standalone one... respect....
699
by: mike420 | last post by:
I think everyone who used Python will agree that its syntax is the best thing going for it. It is very readable and easy for everyone to learn. But, Python does not a have very good macro...
1
by: Colin McKinnon | last post by:
Hi all, I'm wondering if anyone can recommend a PHP documentor which *works* phpXref-0.4.1 - can't cope with more than one class defn per file phpdoctor-2.0.0RC1 - can only document...
4
by: TT (Tom Tempelaere) | last post by:
Hi, In my project I need to use VirtualAlloc (kernel32) to allocate memory to ensure that data is 4K aligned. I need to fill the data block with file contents. I notice that there are no 'Read'...
8
by: Rich | last post by:
Hello, If I leave Option Strict Off I can use the following syntax to read data from a Lotus Notes application (a NotesViewEntry object represents a row of data from a Lotus Notes View - like a...
4
by: Baron Samedi | last post by:
hi, I would like to auto-doc some existing code, mostly so I can understand it. I am slowly adding PhpDoc comments, but I miss some tools which I have for C/c++. For instance, the Code Visual...
2
by: vectorizor | last post by:
Hi all, I am writing an image processing algorithm that goes across an image first row-wise and then column-wise. For illustration purposes, imagine that for every pixels, the output is computed...
5
by: Al G | last post by:
Hi, I'm converting a bit of POP3 VB6 code to VB2005, and have run into this error with the following code. Can someone help me find out what I'm missing/doing wrong? 'holds the attachments...
2
by: Jukka K. Korpela | last post by:
Sub titulo "Re: DIV borders different in IE7 when in td" scripsit Ben C: This seems to be the heart of the matter, and I'm trying to get a real discussion started, by moving the discussion to...
0
by: DolphinDB | last post by:
Tired of spending countless mintues downsampling your data? Look no further! In this article, you’ll learn how to efficiently downsample 6.48 billion high-frequency records to 61 million...
0
by: ryjfgjl | last post by:
ExcelToDatabase: batch import excel into database automatically...
0
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
0
by: ArrayDB | last post by:
The error message I've encountered is; ERROR:root:Error generating model response: exception: access violation writing 0x0000000000005140, which seems to be indicative of an access violation...
1
by: PapaRatzi | last post by:
Hello, I am teaching myself MS Access forms design and Visual Basic. I've created a table to capture a list of Top 30 singles and forms to capture new entries. The final step is a form (unbound)...
0
by: Defcon1945 | last post by:
I'm trying to learn Python using Pycharm but import shutil doesn't work
0
by: Shællîpôpï 09 | last post by:
If u are using a keypad phone, how do u turn on JavaScript, to access features like WhatsApp, Facebook, Instagram....
0
by: af34tf | last post by:
Hi Guys, I have a domain whose name is BytesLimited.com, and I want to sell it. Does anyone know about platforms that allow me to list my domain in auction for free. Thank you
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.