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.
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.
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.
1.REGARDING COPYRIGHT
Thanks for reminding us of the copyright stuff, Rod. Would the following wordage in the licensing section acknowledge_license_cert.html file work to deal with the many files that are missing copyrights:
License information:
Unless otherwise stated, this code is subject to the terms of the GNU General Public License version 3 or higher (GPL), a copy of which is included here for your convenience. Additionally, unless otherwise stated, the code is copyrighted (2002-2012) by Synitech, Incorporated.
(I am not including Pennington firm because they have not placed any copyrights on any of their files (if they even created new files) and it is basically impossible to derive what “Extensive modifications to the code base” they made, so I don’t see any reason to include this.)
2. REGARDING LICENSE
Here’s what I propose to place on the page block header for the library/sql.inc page:
/**
* Sql functions/classes for OpenEMR.
*
* Includes classes and functions that OpenEMR uses
* to interact with SQL.
*
* LICENSE: This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://opensource.org/licenses/gpl-license.php>.
*
* @package OpenEMR
* @copyright 2002-2012 Synitech, Incorporated
* @license http://opensource.org/licenses/gpl-license.php GPL (Version 3 of the License, or (at your option) any later version.)
* @link http://www.open-emr.org
*/
Hi Brady, my understanding is that copyright statements are no longer necessary to protect copyright. To say “unless otherwise stated” doesn’t seem right because many (perhaps most) modules have multiple authors, thus multiple copyright holders, however only the original copyright statement is usually present. Ultimately the commit history will be the best source of copyright information.
I’d suggest not “fixing” old or missing copyright statements or making blanket claims about copyright because it will be difficult to do that comprehensively, and it doesn’t seem necessary.
Also if it matters, the date range for Synitech would be 2002-2003 (not 2002-2012) as they were not involved after 2003.
IMHO, Copyright notice is not required in the U.S., but is still a good idea. See http://www.copyright.gov/circs/circ03.pdf and http://en.wikipedia.org/wiki/Software_license. Copyright gives the holder rights, which are the basis for a credible license. Just saying it is the “GNU General Public License” is not really enough since the legal document has to be accessible. Also, IMHO the complications in all this arise from commercial product licenses and all the efforts to make them effective and enforceable. I do not advocate slacking on copyright or license notices, but we do not have to go to great lengths either, since the whole point of open-source is not keeping things under wraps. The most important part of the text example is the warranty disclaimer. AFAIK, we want to recognize contributors and don’t want someone taking the code and not having to honor the GNU General Public License.
Since the example above has two links to the license, one is extra. I would keep a copyright tag if someone uses it, but otherwise would not worry about it. My 2 cents. No more comments from me on the copyright/license.
I made some example DocBlocks, but I put in html markup and saved it as .html. I was looking at the http://www.mediawiki.org/wiki/Help:Formatting page and it seems it would be better to have the examples in plain text. Isn’t the idea to give Brady some examples that he can easily add to the wiki page? I am going to add something about the .ini files because I think a contributor might want to be able to check documentation for only their project files. At least mentioning how this might be done could be helpful.
It is my understanding that in order to reassure potential financial contributors to the project, all parts of the code must have some attribution and a statement from the contributor that is has been released under some open source license. This prevents someone from bringing a property rights suit against the project in the future. Sam Bowen please clarify if I have misinformed here.
Perhaps attribution with an open source release is different from a copyright or copyleft for that matter; I’m over my head here. Just wanted this clarified before we make an official policy.
Looks good overall. My suggestion it to make it clear what recommend for the two most common things; page-level block and function block since this are the most common things to be documented:
page-level block (I see no reason to recommend use of the copyright or license tags since are redundant and just cause confusion; my main concern is that we can not lose ability to automatically upgrading the GPL to 4 in future by mistakenly truncating any of the text.):
/**
* Upgrading and patching functions of database.
*
* Functions to allow safe database modifications
* during upgrading and patches.
*
* Copyright (C) 2008-2012 Rod Roark <rod@sunsetsystems.com>
*
* LICENSE: This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://opensource.org/licenses/gpl-license.php>.
*
* @package OpenEMR
* @author Rod Roark <rod@sunsetsystems.com>
* @author Brady Miller <brady@sparmy.com>
* @link http://www.open-emr.org
*/
function block:
/**
* Check if a Sql row exists. (with two values)
*
* This function will check if a selected sql row exists that contains two
* known values.
*
* @param string $tblname Sql Table Name
* @param string $colname Sql Column Name 1
* @param string $value Sql value 1
* @param string $colname2 Sql Column Name 2
* @param string $value2 Sql value 2
* @return boolean returns true if the sql row does exist
*/
function tableHasRow2D($tblname, $colname, $value, $colname2, $value2) {
$row = sqlQuery("SELECT COUNT(*) AS count FROM $tblname WHERE " .
"$colname LIKE '$value' AND $colname2 LIKE '$value2'");
return $row['count'] ? true : false;
}
Regarding the files that are blank (ie. no copyright or license info). If somebody were so inclined, couldn’t they ascertain these by comparing to synitech V2 OpenEMR code: http://www.synitech.com/openemr/download/openemr-2.0.0.tar.gz
(This would be the synitech copyright info with GPL2)
My suggestion it to make it clear what recommend for the two most common things
I used the examples you posted above and rewrote the examples section. I know we want to keep documentation guidelines as simple as possible, since any documentation is likely better than none, but I want to note that using @package OpenEMR for every file will probably create a huge index.html for the documentation. Naturally, the PhpDocumentor has the @category, @package, @subpackage tags to aid in making a documentation tree - at least as I understand it. (complication grows exponentially) This is something to be aware of while we are seeing how the documentation works out.
I plan to play around with the PhpDocumentor .ini file some and, if I come up with anything useful, will add that information.
Re identifying Synitech stuff, note the SF CVS start code includes some code contributions from Pennfirm, me and others (I got involved around March '05, and Pennfirm did some stuff before that but after Synitech).
Kevmccor’s point about copyright laws outside the U.S. is a good one. Somewhere there should probably be a statement along the lines of “Portions copyright 2002-2003 Synitech Incorporated”. Perhaps in a COPYRIGHT_AND_LICENSE file that gives an overview of copyright and licensing? I’d avoid being more specific than we are prepared to back up.
Played around with the category and subpackage stuff in PhpDocumentor and couldn’t get it to work. For now, figured just best to make it as simple as possible and force a package name of OpenEMR (note a package tag forces it to be considered a page level doc). Then at some point when we get a better feel for the documentation and how to organize it, we can begin to organize the code/documentation better by modifying package parameters and adding subpackage/categories.
I updated the wiki page accordingly. We might get some ideas from PHPUnit. https://github.com/sebastianbergmann/phpunit I was just looking around for some projects that used PhpDocumentor and this one is fairly well known and well documented. The few files I looked at had the @package and @subpackage tags and did not use @category tags. Like you say, when we get a better feel for it is when to try and establish organization.