cipher-naught wrote on Friday, June 15, 2012:
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
cipher-naught wrote on Friday, June 15, 2012:
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
fndtn357 wrote on Friday, June 15, 2012:
is anyone using Doxygen? Seems to play very well with documented code.
kevmccor wrote on Friday, June 15, 2012:
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.
kevmccor wrote on Sunday, June 17, 2012:
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
pear channel-update pear.php.net
pear config-set data_dir [ -- /path/to/public_html/pear -- ] (like /var/www/htdocs/pear)
pear upgrade PhpDocumentor
Anyone have any preferences?
bradymiller wrote on Monday, June 18, 2012:
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
tmccormi wrote on Monday, June 18, 2012:
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
yehster wrote on Monday, June 18, 2012:
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
* @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 versiontmccormi wrote on Monday, June 18, 2012:
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
kevmccor wrote on Monday, June 18, 2012:
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?
bradymiller wrote on Monday, June 18, 2012:
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
kevmccor wrote on Monday, June 18, 2012:
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).
yehster wrote on Monday, June 18, 2012:
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.
kevmccor wrote on Monday, June 18, 2012:
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.
bradymiller wrote on Tuesday, June 19, 2012:
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:
sudo phpdoc -t apidocs -o HTML:default:default -d . --ignore apidocs/,gacl/,phpmyadmin/,library/adodb/
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
kevmccor wrote on Tuesday, June 19, 2012:
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.
bradymiller wrote on Tuesday, June 19, 2012:
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
bradymiller wrote on Tuesday, June 19, 2012:
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
bradymiller wrote on Thursday, June 21, 2012:
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
kevmccor wrote on Thursday, June 21, 2012:
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.