Simplified page level docblock

[ivanlanin]

I think the current page level docblock is too long. I've look at some other projects to see how they implement this part. I propose a simplified docblock as follow:

/**
 * PHPWord
 *
 * PHP version 5.3
 *
 * @copyright   2014 PHPWord
 * @license     http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt LGPL
 * @version     0.9.0
 */

If agreed, I'll make the changes.

[gabrielbull]

Do we even need it? The license is included with the project.

[ivanlanin]

I think we stil need a short note about the license, either as link or something like "see LICENSE.md".

[Progi1984]

I agree with @ivanlanin. That will reduce the size of files and the package, and that will simplify the reading of files.

[gabrielbull]

Maybe we can remove the version at least? So we don't have to update EVERY file for EVERY release?

[Progi1984]

We must simplify the header :

/**
 * @copyright   2014 PHPWord
 * @license     http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt LGPL
 */

[ivanlanin]

phpdoc needs a summary line. I also think that we should "advertise" ourself. How about this:

/**
 * PHPWord
 *
 * @link        https://github.com/PHPOffice/PHPWord
 * @copyright   2014 PHPWord
 * @license     http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt LGPL
 */

[Progi1984]

I agree with this one...
What do you think about it, @gabrielbull ?

[gabrielbull]

It's fine by me.

[ivanlanin]

Ok. Thanks. I'll make the changes.

[ghost]

It seems that we have to include copyright notice in each source file. Please, find the details here.

[ivanlanin]

I've just read the page that you pointed. You're right. The page said:

"... the process involves adding two elements to each source file of your program: a copyright notice ..., and a statement of copying permission ..."

I looked at some popular FOSS and I found that most of the FOSS that use short header are using MIT license. I also found that they put individual names instead of team name.

[ghost]

Moreover, we need to use date range instead of 2014, because the project wasn't born this year.

[ivanlanin]

I've consulted my friend, an IPR consultant, and here's the simplest form that we're proposing:

/**
 * This file is part of PHPWord - A pure PHP library for reading and writing
 * word processing documents.
 *
 * PHPWord is free software distributed under the terms of the GNU Lesser
 * General Public License as published by the Free Software Foundation.
 * For the full copyright and license information, please read the LICENSE
 * file that was distributed with this source code.  For the full list of
 * contributors, visit https://github.com/PHPOffice/PHPWord/contributors
 *
 * @copyright   2010-2014 PHPWord contributors
 * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
 * @link        https://github.com/PHPOffice/PHPWord
 */

That form complies with FSF requirements.

Update: I've updated the recommendation to reflect the role of our contributors.

[ghost]

OK. Thanks to you and to your friend. Let's stick with this one.

/**
 * This file is part of PHPWord - A pure PHP library for reading and writing
 * word processing documents.
 *
 * PHPWord is free software distributed under the terms of the GNU Lesser
 * General Public License version 3 as published by the Free Software Foundation.
 *
 * For the full copyright and license information, please read the LICENSE
 * file that was distributed with this source code. For the full list of
 * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
 *
 * @copyright   2010-2014 PHPWord contributors
 * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
 * @link        https://github.com/PHPOffice/PHPWord
 */

I added the exact version of the license and made some minor corrections.

[ivanlanin]

I agree. This format looks better. I think @Progi1984 and @gabrielbull will agree. What do you think, guys?

[Progi1984]

Euh... Can I just answer : "Perfect" ?

[ivanlanin]

Yes you can :) Can you implement the changes, @RomanSyroeshko? I'm using Windows and I haven't found a good tool to do bulk block changes easily. Thanks before.

[ghost]

@ivanlanin, I'm on Windows too, but I'll do it later. :)

[ivanlanin]

Ah, I see. Thanks. I can do bulk line changes easily but can't do that for block changes like this one. Do you have any tools for that?

[ghost]

Nope.

[ivanlanin]

Whew. 200+ manual block changes will be quite tiring :)

[ghost]

My fingers are extremely fast. :)

[ivanlanin]

We're counting on them :) Thanks.