We use comments in source files identify the meaning of the process at a later stage in the projects. Code comments are important since change requirements can occur after months and maybe years after releasing project. So its important to have them in order to refresh and figure out what this actually means. No matter which programming language you use, commenting code is essential.

---

In this post i am going to explain how to read comment code inside your files using php and practical usage of comments. Every web application needs a user documentation well as developer documentation. It takes time to create a developer documentation manually. So ill explain how to use code comments inside your php files to generate a simple developer documentation. Lets start by identifying the comment lines and extracting them using php regex.

Using php regular expressions you can filter out contents between 2 given delimiters or symbols. Since we are focusing on filtering comments, my example contains content between start and tag of multi line comments in php. You can prepare the regex according to the delimiters you want to filter.

        // $comment is the string generated from reading file - contains comments
        // $match will have all the filtered comments after execution
        preg_match_all("/\/\*.*?\*\//",$comment,$match,PREG_OFFSET_CAPTURE);

Regex for filtering multiple comments

Regex = “\/\*.*?\*\/”;

This expression can be broken down into 3 main parts

part 1 = \/\* -> Finds the starting tag of comments (/*). You can change this to define any delimiter you like.
part 2 = .*? -> Finds string with any number of characters
part 3 = \*\/ -> Finds the ending tag of comments (*/). You can change this to define any delimiter you like.

Define Comment and Documentation Syntax

First you have to define a common formatted syntax for all the comments and match it every time you use comments. Following example contains a simple comment syntax.

     /*
       @function -> startComment
       @parameters -> comment=>string,type=>int
       @description -> Test Start Comment Reading Using Php
     */
    public function startComment(){

    }

In the above example i have defined a common syntax for all the functions. All the main sections are separates by ‘@’ sign and all the values for main sections are separated by ‘->’ sign. You can customize this syntax according to your requirement. Here i have defined function,parameter and description as main sections. so whenever someone reads the code it easier to identify process and parameters needed.

 

Reading the Files in the Project Folder

Next you have to read all the source files inside the project folder one by one. Use a recursive function to traverse through the directories and read files. Then read the file content into a string using fread and parse it to read comment function to extract values.

 

Extracting Documentation Data using Comment Reader

Create a method to extract the comment data in the file. Following function is a sample code to process the comment data according to my syntax. You will have to change the method according to your syntax.

function read_comments($match) {


    $output_string = "

"; /* * Traverse through each filtered comment block */ foreach ($match[0] as $key => $value) { /* * Single comment block */ $single_comment = $value[0]; /* * Get each comment section - Ex: @function -> startComment */ $comment_sections = explode("@", $single_comment); foreach ($comment_sections as $key => $value) { if ($key != 0) { /* * Remove start and end comment tags */ $filtered_comment = str_replace('/*','',$value); $filtered_comment = str_replace('*/','',$filtered_comment); /* * Break each section into key and value - Ex:key=function,value=startComment */ $section_key_value = explode('->',$filtered_comment); $output_string .= ""; } } $output_string .= ""; } echo $output_string."

Innovative Developer Doc
".$section_key_value[0]."	". $section_key_value[1]."

"; }

Use the code comments to understand the logic behind the code.

 

Publishing Documentation

Once you generate all the comment data use html table or design like the one in the above example and publish as developer documentation. Once created make sure you give the file permission back to original state. To read php files you may need to give file permission according to permission level in linux.

 

Sample Published Developer Doc

Innovative Developer Doc
function	startComment
parameters	comment=>string,type=>int
description	Test Start Comment Reading Using Php
function	endComment
parameters	comment=>string,type=>int
description	Test End Comment Reading Using Php

This is only a simple example for creating developer documentation. You can create your own comment syntax to generate fully featured documentation with links to other classes and functions like the java doc. I am going to develop and explain a fully featured doc in a future tutorial.

Download Comment Reader