Solved

Opinions on PHPDOC as a documentation aid

Posted on 2010-08-16
4
525 Views
Last Modified: 2012-06-27
Opinions please

PHPDOC has been around as a documentation standard for a while and is obviously based on JavaDoc. The ability to generate pages of HTML documentation is obviously nice but it does have the downside of producing documentation that is not directly tied in to the source code - over time the source code can change but the documentation does not (unless you remember to regenerate it).

The other aspects are

1) The visual appearance of the comments
2) The need to be accurate in producing the comments in a given format

I have always found the format of the comments too visually impactive - the comment takes over and you loose sight of the code  very quickly, for instance

     protected $email;       // Contact email address
     protected $name;      // Customer's name

as opposed to
 
     /**
      * Contact email address
      * @var string
      */
     protected $email;

     /**
      * Customer name
      * @var string
      */
     protected $name;l


Even with just two of these, the  declaration between the comments is much more visually invisible and when you have a dozen such declarations and comments you soon lose sight of the working code in the sea of comment code

Something deep in my programmer's soul tells me that I should be producing code that can be automatically documented whilst the pragmstist in me shouts that no one ever reads documentation - they read the code instead.

None of the code at present is available for public release so this would be an internal exercise and decision. I can easily enough transform our existing code libraries over to the PHPDOC format by use of a small program and regexes, but should I bother? I'm not convinced so I'd appreciate opinions.

0
Comment
Question by:Beverley Portlock
[X]
Welcome to Experts Exchange

Add your voice to the tech community where 5M+ people just like you are talking about what matters.

  • Help others & share knowledge
  • Earn cash & points
  • Learn & ask questions
  • 3
4 Comments
 
LVL 16

Accepted Solution

by:
HackneyCab earned 500 total points
ID: 33445448
Well, I have to say honestly that it sounds like you've made your decision already. But, for what it's worth, I'm very happy with phpDocumentor:

http://www.phpdoc.org/

I use Netbeans as an IDE for PHP, and with a little configuration you can run phpDocumentor on your entire project just by hitting F6. And as for the look of the HTML produced, you can pick from one of several styles, or (if you're really determined to have a certain look) create your own transformation template. Also, in Netbeans (with the PHP mode) your bulky phpDoc comment blocks do you another favour: by declaring the type of a declared variable (type string in the case of your examples, but it's mostly useful when declaring objects) Netbeans knows which class a variable belongs to, and it can show you what methods are available to an object of that class. Very handy.

As for people reading code rather than documentation, I couldn't agree less. Reading code is great for a script of two or three linear files, but once you're using OOP and you're calling the API of a dozen or so classes, you don't care about the code, you just need to know the method signature (what a method is for, what parameters it takes, and what it returns), and the sort of documentation produced by phpDocumentor is perfect for this.

I will admit that combining a tutorial document into the HTML produced by phpDocumentor is a faff (you have to write the documentation in DocBook format) but to have the option to package API and tutorial together is nice. Also that I don't use phpDocumentor to document page scripts (which simply make calls to classes and are as short as possible), where standard comment lines are adequate.
0
 
LVL 34

Author Comment

by:Beverley Portlock
ID: 33452559
"Well, I have to say honestly that it sounds like you've made your decision already."

No I haven't.

I'm trying to decide if it is worth the bother of applying it retrospectively to 70,000 lines of library code. Setting aside the effort involved, what will I have at the end of the exercise other than a set of documentation? At present each class resides in it own source file with the same name as the class and the files are grouped by folder. We use Eclipse rather than netbeans and the IDE has a list of all methods and we use standard naming conventions as far as possible.

I guess what I'm aiming at here is what other benefits accrue from PHPDOC? Are there any others? It seems sensible to use a documentation standard if one exists, especially an automated one, but will it get me anything more than a prettily formatted pile of paper in a ring binder that will never be opened?

Does anything else out there utilise PHPDOC comments for any other purposes? When I lived in the IBM midrange world, a comment attached to data definitions and the like would travel throughout the system and pop up in utuilities and screen layout programs, etc. Commenting things was practically a necessity.



0
 
LVL 34

Author Closing Comment

by:Beverley Portlock
ID: 33453400
I guess we will just have to have a debate internally.

Thanks for your input HackneyCab
0
 
LVL 34

Author Comment

by:Beverley Portlock
ID: 33584382
FYI - After an internal discussion the developers have decided to adopt PhpDoc as an internal standard and the existing code base will be automatically converted over.
0

Featured Post

Why Off-Site Backups Are The Only Way To Go

You are probably backing up your data—but how and where? Ransomware is on the rise and there are variants that specifically target backups. Read on to discover why off-site is the way to go.

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

Build an array called $myWeek which will hold the array elements Today, Yesterday and then builds up the rest of the week by the name of the day going back 1 week.   (CODE) (CODE) Then you just need to pass your date to the function. If i…
This article discusses how to create an extensible mechanism for linked drop downs.
Learn how to match and substitute tagged data using PHP regular expressions. Demonstrated on Windows 7, but also applies to other operating systems. Demonstrated technique applies to PHP (all versions) and Firefox, but very similar techniques will w…
This tutorial will teach you the core code needed to finalize the addition of a watermark to your image. The viewer will use a small PHP class to learn and create a watermark.

695 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question