3

The DocBlocks section of the Coding Standards Manual is mostly self-explanatory, but I've never been sure about two elements - since and copyright.

since - is that for the Joomla version or my component's (arbitrary) version number? Probably the former, but I'd like to be certain.

copyright is a little more tricky. It's obvious if it's a method or class I've built from scratch, but what if half the code's come from a Joomla component? What if all I did was add a line? I've no idea what to put in the copyright element in situations where authorship is mixed.

4

@since should be used to state the version that your component implemented this specific function/class/property/etc..

For example:

/**
 * This function does something
 *
 * @since 1.2
 *
 */

public function foo()
{
    // do something
}

This above means you added the foo() function in v1.2 of your extension.

Depending on how you build and release your extension, you can also use a constant, like Joomla do, for example: @since _DEPLOY__VERSION_

Joomla build released through command line. The version is set when building, which then un turn, replaces all instances of _DEPLOY__VERSION_


As for @copyright, for me personally, there are 2 scenarios.

If I've copied an entire file and made some tweaks:

/**
 * @package     Joomla.Site
 * @copyright   Copyright (C) 2005 - 2016 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 * 
 * Modified by NAME
 */
class Foo {
    public function bar() {};
}

If I've written my own class and copied a couple of functions from Joomla

/**
 * @package     MY COMPONENT
 * @copyright   Copyright (C) 2016 - MY COMPANY
 * @license     MY LICENSE
 */
class Foo {

    /**
     * @copyright Copyright (C) 2005 - 2016 Open Source Matters, Inc. All rights reserved.
     */
    public function bar() {};
}

Hope this helps

  • Cheers mate. Since is answered definitively. Your copyright approach is pretty much what I've been doing and is as good an answer as I hoped to get, but in all honesty given it's a tag that has an attachment, however distant, to lawyers I'd have appreciated clear guidelines from the Project Team. They really should add a little more detail in the CSM. – chrBrd Nov 18 '16 at 17:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.