License docblocks, can we make it better (and smaller)?

[fballiano]

Hi everybody,
at the moment every file in our repo has this docblock

 * OpenMage
 *
 * This source file is subject to the Open Software License (OSL 3.0)
 * that is bundled with this package in the file LICENSE.txt.
 * It is also available at https://opensource.org/license/osl-3-0-php
 *
 * @category   Mage
 * @package    Mage_Shell
 * @copyright  Copyright (c) 2022 The OpenMage Contributors (https://www.openmage.org)
 * @license    https://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)

I notice a few things:

• the @license link (last line) needs a small update since opensource.org changed their pages URLs (they've redirects so it's not a real problem)
• the license link is duplicated, it's present both in the descriptive text and in the @license, and the first line of text also states that the file is under OSL. So we've written that the file is OSL 3 times in a few lines of text, do we really need that?

Do you think we can make this text/docblock better and smaller?

Symfony does it this way:

/*
 * This file is part of the Symfony package.
 *
 * (c) Fabien Potencier <[email protected]>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

Wordpress doesn't seem to have a license docblock https://github.com/WordPress/WordPress/blob/master/wp-login.php

Laravel neither https://github.com/laravel/framework/blob/10.x/src/Illuminate/Conditionable/HigherOrderWhenProxy.php

Magento 2 has this:

/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */

[fballiano]

we could actually shrink it to one line

/**
 * This file is part of OpenMage, see LICENSE.txt for license details.
 * 
 * @category   Mage
 * @package    Mage_Shell
 * @copyright  Copyright (c) 2022 The OpenMage Contributors (https://www.openmage.org)
 * @license    https://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */

[kiatng]

+1 for one liner.

[fballiano]

although "see license.txt for license" sounds pretty bad :-D but it seems it's widespread enough

[fballiano]

This could also be another option:

/**
 * This file is part of OpenMage.
 * 
 * @category   Mage
 * @package    Mage_Shell
 * @copyright  Copyright (c) 2022 The OpenMage Contributors (https://www.openmage.org)
 * @license    https://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */

I think we could avoid writing the "check license.txt" since we've copyright and @license a few lines below

[luigifab]

OSL and AFL

[fballiano]

we never has the AFL line in the @license tag not in text so I wouldn't change that. if you check the source code you'll see that AFL is only used for js/css/xml so I'd not change the @license tag in a general way.

[colinmollenhour]

For the benefit of all watching this discussion, Sven has updated his PR with a new proposal that moves the bulk of the text to COPYING.txt: #4467
If you have any specific objections to the PR, please speak now. :)

[sreichel]

Thanks for your suggestion.