Over at the OpenEMR and Zend discussion the topic of coding guidelines and documentation came up. I thought it might be good to separate that into a different thread.
-ciperh-naught
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
PHPDoctor http://peej.github.com/phpdoctor is very simple to use. You edit a short ini file with the path to your project and some other items and run it from the command line.
$ php phpdoc.php my_project.ini
If you download GeSHi and put the geshi folder in the phpdoctor folder it will generate formatted code in html.
PHPDoctor creates the apidoc folder in your project and puts all its output there: project/apidoc/index.html. So you could just have a link to that folder and you could have wiki access of sorts. As far as documentation goes, PHPDoctor really needs Javadoc format comments in the source code to generate anything more than a plain listing, but with Javadoc comments it would probably be fairly useful. It lists namespaces, classes, functions, constants, globals, etc. There is reference to a class tree. I ran it on my openemr/interface/super directory and it is easier to see what goes on. It makes me think there will need to be a cloned project tree so people can create documentation.
I will download and try to install phpdoc tomorrow. Since Tony suggested it, my guess is it is the likely candidate.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I looked at phpDocumentor 2 http://www.phpdoc.org/ today. It requires php-5.3.3 or greater and also required that the original source code be well documented in the Javadoc format, which it calls a DocBlock. It has extensive capabilities and also works from the command line. I had to upgrade my php-5.2.17 to use it and I also had to install GraphVis.
Is there still a problem with php-5.3 and OpenEMR? I had a problem a while back, but php-5.2.17 works great, so I haven't given it much thought.
Don't think any problems with php 5.3 and OpenEMR (in fact, if use most recent patch for 4.1.0, then hopefully should even work with php 5.4).
No preferences here regarding the tool you use. Once you have something, let us know, so can then figure out how to get published for others to see (goal is to get it on the project website at www.open-emr.org ).
The tool to generate wiki pages or whatever is the *LEAST* important piece of this. Simply having Docblock style comments which describe components in the source code to begin with is what matters most.
As harsh as this sounds, perhaps we should decry that no new functions/features will be accepted without at least minimal docblock comments, and when making changes to existing code, an attempt should be made to improve documentation.
* @abstract
* @access public or private
* @author author name <author@email>
* @copyright name date
* @deprecated description
* @deprec alias for deprecated
* @example /path/to/example
* @exception Javadoc-compatible, use as needed
* @global type $globalvarname
or
* @global type description of global variable usage in a function
* @ignore
* @internal private information for advanced developers only
* @param type [$varname] description
* @return type description
* @link URL
* @name procpagealias
or
* @name $globalvaralias
* @magic phpdoc.de compatibility
* @package package name
* @see name of another element that can be documented,
* produces a link to it in the documentation
* @since a version or a date
* @static
* @staticvar type description of static variable usage in a function
* @subpackage sub package name, groupings inside of a project
* @throws Javadoc-compatible, use as needed
* @todo phpdoc.de compatibility
* @var type a data type for a class variable
* @version version
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
For the overall file/script
* @abstract
* @author author name <author@email>
* @copyright name date
* @deprecated description and date
* @param type description
* @return type description
* @todo phpdoc.de compatibility
Add for the specific class/function where relevant
Be nice to have a tag like @modifiedby that would have name/date/desc of any major mods to the original code
maybe the @internal tag? and @version tags
-Tony
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Which documentation generator does appear to be somewhat unimportant, but there should be one. It appears they all have the common feature or allowing the user to set the output directory, so that documentation html is in a folder "apidoc," "mydoc" or whatever. So where does the output directory go and how do we keep them from being duplicated and over-written by some different documentation?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
In choosing a documentation generator, would be nice to do the following:
1. Choose one that does not require DocBlock to pick up the scripts/classes/functions (meaning, it will at least pick up the names, which is helpful when figuring out what needs to be converted to DocBlock etc.).
2. Placing it in a directory entitled apidoc should be fine.
I think all the ones I mentioned will recognize that a constant, function, class, etc. is present and show the name and the arguments. There will be no commentary if the DocBlock is missing. I think the main point of preference will be integration with a development IDE. Netbeans has this feature for phpdoc. My favorite editor is geany, but it doesn't have a documentation integration feature. However, all the documentors can be run from the command line as well.
So basically, the idea of an "apidoc" folder is OK. That introduces a possibly small complication in a folder that has a lot of scripts. All these documentators implicitly assume that the subject folder is a self-contained module or related code by default. One can exclude files, for example phpdoctor has the "ignore" directive in its my_project.ini file.
In a folder such as openemr/interface the documentation would have to be in specific folders for related scripts, with an "ignore" list that developers would have to verify.
I feel like I am slipping down the java (void) slope.of.infinite.specificity(_already).
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I feel like I am slipping down the java (void) slope.of.infinite.specificity(_already).
This is why I suggest we worry only about the documentation requirements for code acceptance first and worry about what tool the project uses later (or even let folks choose their own tools). Just like we don't all have to use the same IDE (although I vote strongly for NetBeans too ;) We don't have to agree on a document generator just yet.
If we don't have quality documentation to begin with, the output/formatting of the doc generator is irrelevant. Garbage in/garbage out as they say. I am certain that if you asked PHPDoctor to generate a list of all the global variables in the project it would be useless presently. You'll get stuff like $tmp,$atmp,$btmp all over the place.
A depth first (focus on documenting specific components) approach rather than breadth first (lets see all what should be documented) seems like it would be more likely to generate something useful.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I put my initial draft on github at https://github.com/kevmccor/code-doc-oemr. It is very rough and needs styles and doesn't get into any detail yet. I haven't picked an example to describe in detail, but there are the beginnings there. I already have one issue in describing the basics of git - maybe we don't even want to mention it, but I would like to have it well explained for my own benefit.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Disagree with yehster. This can be dealt with on both sides:
1. Enforce proper documentation of new functions/classes/scripts in DocBlock format
2. Publish a public API via PHPDoctor, and use this to walk through the code and improve the documentation and auto-created document organization(@package etc.). Rinse and repeat etc.
For example, created a set of API docs from OpenEMR with below command:
(note this took 3GB of memory and about 10 minutes to build and sizer is 30 megabytes)
Obviously, this has a ways to go. But now a carrot has been provided to potentially motivate other contributors to better document the codebase and improve the output of the above API.
(kevmccor; as you improve on this, I'm happy to push your more refined versions to the website)
What would be cool is a link to a script that would display the code or maybe direct to a repository and "pretty-print" the file. Actually, the next thing is to look at what you made and ask "How useful is that?" I'm not being a critic, just suggesting that it would help me to have an idea of what to suggest to get the documentation more focused and topical, since people will read it in order to help themselves with some particular question or issue. Even so, your apidoc is fairly helpful as is.
I believe you actually used phpDocumentor and not phpDoctor. I think they all answer to phpdoc on the command line. The output is similar as well.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
At this point, it borderlines on not very useful vs. novelty :)
The things to think about are:
1) What else should be filtered out (such as the adodb stuff in the calendar module)
2) Where a good script to make an example of standardized documentation (maybe do on the library/user.inc script). Over time
3) Play around with the output settings or other documentation tools
Meanwhile, we can continue to place them on the website and they should become more useful over time.
This brings up a couple good issues, which we need to answer before going forward:
1. Is that @license tag good enough to avoid needing to copy/paste the other license text we use?
2. For files that do not have copyright info (this is needed), what should we do (I noted some projects just use something like 'The OpenEMR Development Team' but this seems weird)? Could also just place one of the first known authors of that file in the repo (this is generally going to be Rod in most cases)?
4. For file with no author info, what should we do (I basically did a 'git shortlog library/sql.inc' to get an idea of contributors)? But this isn't required, so perhaps best not to include if none are listed?
Once we have these standard worked out, then easier to tell developers what to do with new code and others that feel compelled to document the older code.
I have been looking at the documentation programs and trying to put together a guide that is helpful and short. You are using the phpDocumentor and I think you should look at http://www.phpdoc.org which is the second generation (current) project, with the name phpDocumentor2. It is equally simple to install and use, supposedly better, and has some extra themes which I have not tried.
In the Documentation, they discuss a "template" that can be created which may answer your issues on copyright and author. I guess something like adding a copyright block and author if not present or perhaps with the @project tag. I don't know for sure, but it looks possible. Ironically, their tutorial type documentation is incomplete.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Was just hoping to settle on good example docblock templates to guide developers when documenting page headers, class headers and function headers. I figured the most educated way to come to a conclusion on what to recommend would entail looking at the end-product also. Please feel free to use whatever documenting template system you deem necessary (hopefully the info I placed on the wiki page, such as which directories/files to ignore will be helpful) and I'll glady place your produced documentation onto the website to replace mine.
The documentation for library/sql.inc (linked above) is a nice example since it has a page, class and functions headers in docblock. The class and function headers seem straightforward. It's the page header that we need to come to an agreement on by answering my questions above. Otherwise it's gonna be tough to "recommend" a specific format for the page headers. The big questions are:
1. Will the @license tag I used suffice to replace the other license jargon?
2. What do we do for old scripts that do not have any copyright?
1. Will the @license tag I used suffice to replace the other license jargon?
2. What do we do for old scripts that do not have any copyright?
I believe the @license tag is sufficient. I was looking at that from a legal angle as to whether it was sufficient notice. I think something in text about the GPL should be included, but it could be much abbreviated.
This program is distributed under the terms of the GNU General Public License published by the Free Software Foundation WITHOUT ANY WARRANTY, express or implied, including any implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
I believe you should add the @package tag to your page level Dock Block. The @package tag is used by the PhpDocumentor to group related files and classes, which will be important. Put the @license tag under the @copyright tag.
I decided you were right in choosing PhpDocumentor instead of phpDocumentor2. Version 2 is not prime-time ready IMHO.
I still don't know what to do about files that lack a copyright notice.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Regarding license stuff, gonna start looking through other projects to see how they deal with this.
Regarding copyright stuff, considering making it one of the first contributing authors to a script if missing (and will make sure the author is ok with it). Note, this will almost always end up being Rod (are you ok with this Rod?). Anybody else have thoughts on this copyright issue?
About missing copyright statements - no, I've been pretty diligent about inserting them for modules where I am the original author. Older releases of OpenEMR had a "copyright_notice.html" which included this:
The original version of OpenEMR was developed and copyrighted (2002-2003) by Synitech, Incorporated.
www.synitech.com
145 Brick Kiln Place; Cheshire, CT 06410
Extensive modifications to the code base have been made and copyrighted (2003-2004) by Pennington Firm.
www.pennfirm.com
402 West Broadway; 4th Floor; San Diego, CA 92101
My best guess is that Synitech was the original author of most or all modules where copyright is missing. I'm not sure what the best way to acknowledge that is.
Rod
www.sunsetsystems.com
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Updated draft on github at https://github.com/kevmccor/code-doc-oemr. I think the DocBlock examples are fairly useful and cover most cases. Perhaps the beginning material is off topic now, but I was hoping to get/create some guidance on basic integration requirements. It is still a draft and is probably completely the wrong format for a wiki page.
BTW, missing copyright might be the same as no copyright. Maybe there is a copyright notice that applies to an entire group of old files, like a notice in the main file that includes the others.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Over at the OpenEMR and Zend discussion the topic of coding guidelines and documentation came up. I thought it might be good to separate that into a different thread.
-ciperh-naught
A question I had for documentation is if any of the tools out there like PHPDoctor and phpdoc have connectivity to the wiki system?
It would be nice to connect the coding documentation to the wiki for further or different discussion.
Any thoughts?
-cipher-naught
is anyone using Doxygen? Seems to play very well with documented code.
PHPDoctor http://peej.github.com/phpdoctor is very simple to use. You edit a short ini file with the path to your project and some other items and run it from the command line.
If you download GeSHi and put the geshi folder in the phpdoctor folder it will generate formatted code in html.
PHPDoctor creates the apidoc folder in your project and puts all its output there: project/apidoc/index.html. So you could just have a link to that folder and you could have wiki access of sorts. As far as documentation goes, PHPDoctor really needs Javadoc format comments in the source code to generate anything more than a plain listing, but with Javadoc comments it would probably be fairly useful. It lists namespaces, classes, functions, constants, globals, etc. There is reference to a class tree. I ran it on my openemr/interface/super directory and it is easier to see what goes on. It makes me think there will need to be a cloned project tree so people can create documentation.
I will download and try to install phpdoc tomorrow. Since Tony suggested it, my guess is it is the likely candidate.
I looked at phpDocumentor 2 http://www.phpdoc.org/ today. It requires php-5.3.3 or greater and also required that the original source code be well documented in the Javadoc format, which it calls a DocBlock. It has extensive capabilities and also works from the command line. I had to upgrade my php-5.2.17 to use it and I also had to install GraphVis.
Is there still a problem with php-5.3 and OpenEMR? I had a problem a while back, but php-5.2.17 works great, so I haven't given it much thought.
PhpDocumentor-1 is also available and has a tie in with NetBeans editor (as does phpDocumentor 2). I have downloaded and installed it, but not used it yet.
http://manual.phpdoc.org/HTMLSmartyConverter/HandSric_INSTALL.html
Anyone have any preferences?
Hi,
Don't think any problems with php 5.3 and OpenEMR (in fact, if use most recent patch for 4.1.0, then hopefully should even work with php 5.4).
No preferences here regarding the tool you use. Once you have something, let us know, so can then figure out how to get published for others to see (goal is to get it on the project website at www.open-emr.org ).
thanks,
-brady
OpenEMR
I don't have a strong preference either. I just think we need this process and it should be simple for the programmers to comply with..
-Tony
The tool to generate wiki pages or whatever is the *LEAST* important piece of this. Simply having Docblock style comments which describe components in the source code to begin with is what matters most.
As harsh as this sounds, perhaps we should decry that no new functions/features will be accepted without at least minimal docblock comments, and when making changes to existing code, an attempt should be made to improve documentation.
A good place to begin might be to identify a minimum set of required/suggested tags from the complete set:
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.tags
Here's my put …
For the overall file/script
* @abstract
* @author author name <author@email>
* @copyright name date
* @deprecated description and date
* @param type description
* @return type description
* @todo phpdoc.de compatibility
Add for the specific class/function where relevant
* @package package-name
* @see package.class#member
* @param parameter-type parameter-name description
* @return return-type description
Be nice to have a tag like @modifiedby that would have name/date/desc of any major mods to the original code
maybe the @internal tag? and @version tags
-Tony
Which documentation generator does appear to be somewhat unimportant, but there should be one. It appears they all have the common feature or allowing the user to set the output directory, so that documentation html is in a folder "apidoc," "mydoc" or whatever. So where does the output directory go and how do we keep them from being duplicated and over-written by some different documentation?
Hi,
In choosing a documentation generator, would be nice to do the following:
1. Choose one that does not require DocBlock to pick up the scripts/classes/functions (meaning, it will at least pick up the names, which is helpful when figuring out what needs to be converted to DocBlock etc.).
2. Placing it in a directory entitled apidoc should be fine.
-brady
OpenEMR
I think all the ones I mentioned will recognize that a constant, function, class, etc. is present and show the name and the arguments. There will be no commentary if the DocBlock is missing. I think the main point of preference will be integration with a development IDE. Netbeans has this feature for phpdoc. My favorite editor is geany, but it doesn't have a documentation integration feature. However, all the documentors can be run from the command line as well.
So basically, the idea of an "apidoc" folder is OK. That introduces a possibly small complication in a folder that has a lot of scripts. All these documentators implicitly assume that the subject folder is a self-contained module or related code by default. One can exclude files, for example phpdoctor has the "ignore" directive in its my_project.ini file.
In a folder such as openemr/interface the documentation would have to be in specific folders for related scripts, with an "ignore" list that developers would have to verify.
I feel like I am slipping down the java (void) slope.of.infinite.specificity(_already).
This is why I suggest we worry only about the documentation requirements for code acceptance first and worry about what tool the project uses later (or even let folks choose their own tools). Just like we don't all have to use the same IDE (although I vote strongly for NetBeans too ;) We don't have to agree on a document generator just yet.
If we don't have quality documentation to begin with, the output/formatting of the doc generator is irrelevant. Garbage in/garbage out as they say. I am certain that if you asked PHPDoctor to generate a list of all the global variables in the project it would be useless presently. You'll get stuff like $tmp,$atmp,$btmp all over the place.
A depth first (focus on documenting specific components) approach rather than breadth first (lets see all what should be documented) seems like it would be more likely to generate something useful.
I put my initial draft on github at https://github.com/kevmccor/code-doc-oemr. It is very rough and needs styles and doesn't get into any detail yet. I haven't picked an example to describe in detail, but there are the beginnings there. I already have one issue in describing the basics of git - maybe we don't even want to mention it, but I would like to have it well explained for my own benefit.
Hi,
Disagree with yehster. This can be dealt with on both sides:
1. Enforce proper documentation of new functions/classes/scripts in DocBlock format
2. Publish a public API via PHPDoctor, and use this to walk through the code and improve the documentation and auto-created document organization(@package etc.). Rinse and repeat etc.
For example, created a set of API docs from OpenEMR with below command:
And placed those docs here:
http://www.open-emr.org/apidocs/
(note this took 3GB of memory and about 10 minutes to build and sizer is 30 megabytes)
Obviously, this has a ways to go. But now a carrot has been provided to potentially motivate other contributors to better document the codebase and improve the output of the above API.
(kevmccor; as you improve on this, I'm happy to push your more refined versions to the website)
-brady
OpenEMR
What would be cool is a link to a script that would display the code or maybe direct to a repository and "pretty-print" the file. Actually, the next thing is to look at what you made and ask "How useful is that?" I'm not being a critic, just suggesting that it would help me to have an idea of what to suggest to get the documentation more focused and topical, since people will read it in order to help themselves with some particular question or issue. Even so, your apidoc is fairly helpful as is.
I believe you actually used phpDocumentor and not phpDoctor. I think they all answer to phpdoc on the command line. The output is similar as well.
Hi,
"How useful is that?"
At this point, it borderlines on not very useful vs. novelty :)
The things to think about are:
1) What else should be filtered out (such as the adodb stuff in the calendar module)
2) Where a good script to make an example of standardized documentation (maybe do on the library/user.inc script). Over time
3) Play around with the output settings or other documentation tools
Meanwhile, we can continue to place them on the website and they should become more useful over time.
-brady
OpenEMR
Hi,
Also threw up a quick wiki page that you can feel free to use:
http://www.open-emr.org/wiki/index.php/OpenEMR_API
Placed a link to it in the main wiki page Developers Manual->Main section.
-brady
OpenEMR
Hi,
To have a practical example, I documented the library/sql.inc file in this commit:
http://github.com/bradymiller/openemr/commit/474d87715e1aede955f82336ec5565654c482eaa
This brings up a couple good issues, which we need to answer before going forward:
1. Is that @license tag good enough to avoid needing to copy/paste the other license text we use?
2. For files that do not have copyright info (this is needed), what should we do (I noted some projects just use something like 'The OpenEMR Development Team' but this seems weird)? Could also just place one of the first known authors of that file in the repo (this is generally going to be Rod in most cases)?
4. For file with no author info, what should we do (I basically did a 'git shortlog library/sql.inc' to get an idea of contributors)? But this isn't required, so perhaps best not to include if none are listed?
Here's the newly compiled docs based on this:
http://www.open-emr.org/apidocs/
Specifically, here's the page to the docs describing the library/sql.inc file:
http://www.open-emr.org/apidocs/OpenEMR/_library--sql.inc.html
Tracking this project here:
http://www.open-emr.org/wiki/index.php/OpenEMR_API
Once we have these standard worked out, then easier to tell developers what to do with new code and others that feel compelled to document the older code.
-brady
OpenEMR
I have been looking at the documentation programs and trying to put together a guide that is helpful and short. You are using the phpDocumentor and I think you should look at http://www.phpdoc.org which is the second generation (current) project, with the name phpDocumentor2. It is equally simple to install and use, supposedly better, and has some extra themes which I have not tried.
In the Documentation, they discuss a "template" that can be created which may answer your issues on copyright and author. I guess something like adding a copyright block and author if not present or perhaps with the @project tag. I don't know for sure, but it looks possible. Ironically, their tutorial type documentation is incomplete.
Hi,
Was just hoping to settle on good example docblock templates to guide developers when documenting page headers, class headers and function headers. I figured the most educated way to come to a conclusion on what to recommend would entail looking at the end-product also. Please feel free to use whatever documenting template system you deem necessary (hopefully the info I placed on the wiki page, such as which directories/files to ignore will be helpful) and I'll glady place your produced documentation onto the website to replace mine.
The documentation for library/sql.inc (linked above) is a nice example since it has a page, class and functions headers in docblock. The class and function headers seem straightforward. It's the page header that we need to come to an agreement on by answering my questions above. Otherwise it's gonna be tough to "recommend" a specific format for the page headers. The big questions are:
1. Will the @license tag I used suffice to replace the other license jargon?
2. What do we do for old scripts that do not have any copyright?
-brady
OpenEMR
I believe the @license tag is sufficient. I was looking at that from a legal angle as to whether it was sufficient notice. I think something in text about the GPL should be included, but it could be much abbreviated.
This program is distributed under the terms of the GNU General Public License published by the Free Software Foundation WITHOUT ANY WARRANTY, express or implied, including any implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
I believe you should add the @package tag to your page level Dock Block. The @package tag is used by the PhpDocumentor to group related files and classes, which will be important. Put the @license tag under the @copyright tag.
I decided you were right in choosing PhpDocumentor instead of phpDocumentor2. Version 2 is not prime-time ready IMHO.
I still don't know what to do about files that lack a copyright notice.
Agreed,
Regarding license stuff, gonna start looking through other projects to see how they deal with this.
Regarding copyright stuff, considering making it one of the first contributing authors to a script if missing (and will make sure the author is ok with it). Note, this will almost always end up being Rod (are you ok with this Rod?). Anybody else have thoughts on this copyright issue?
-brady
OpenEMR
About missing copyright statements - no, I've been pretty diligent about inserting them for modules where I am the original author. Older releases of OpenEMR had a "copyright_notice.html" which included this:
Extensive modifications to the code base have been made and copyrighted (2003-2004) by Pennington Firm.
www.pennfirm.com
402 West Broadway; 4th Floor; San Diego, CA 92101
My best guess is that Synitech was the original author of most or all modules where copyright is missing. I'm not sure what the best way to acknowledge that is.
Rod
www.sunsetsystems.com
Updated draft on github at https://github.com/kevmccor/code-doc-oemr. I think the DocBlock examples are fairly useful and cover most cases. Perhaps the beginning material is off topic now, but I was hoping to get/create some guidance on basic integration requirements. It is still a draft and is probably completely the wrong format for a wiki page.
BTW, missing copyright might be the same as no copyright. Maybe there is a copyright notice that applies to an entire group of old files, like a notice in the main file that includes the others.