1

I am writing a module that will eventually be listed in the JED. I'm a bit unsure about how to properly construct docblock comments for each file within a module or plugin. If I have a module that is also part of a package, is this how I write the docblock comments:

/**
 * @package     MyPackageName (or Joomla.Platform or Joomla.Site??)
 * @subpackage  mod_my_module
 * @copyright   Copyright 2005 - 2013 Open Source Matters. All rights re-served.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

Do I need to include LICENSE.txt within the modules folder? If yes, where do I get this file from?

What if my module is not part of any package? Do I then DON'T need to include both @package and @subpackage?

user1448031
  • 2,172
  • 11
  • 44
  • 89

1 Answers1

1

As mentioned on the Joomla Docs, you need to include the following:

  1. package
  2. version
  3. author
  4. copyright
  5. license

like so:

/**
 * @package PACKAGE_NAME
 * @version VERSION_NUMBER
 * @author YOUR NAME HERE
 * @copyright (C) 2013- YOUR NAME HERE
 * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
**/

You can make additions of you own such as including a creation date, modified date etc if you wish.

I have found a lot of extensions that don't use a license.txt file, however just to be on the safe side, include one, however it doesn't need to be installed with the extension.

All requirements are in the link I provided above :)

Update:

I never really use all the information in the "version" section. I simply add the version number and that's it. In the docs though, it all kind of gets combined into one like so:

$Id: 
 - mod_XYZ.php   >> name of file
 - 599           >> version number
 - 2010-03-20    >> date
 - 23:26:33Z     >> time  (not sure what the **Z** is for though) 
 - you           >> author
$

This is not mandatory, as you have already specified the essentials so you can simply use: 

@version 1.2  or   @version 1.3  etc

Hope this helps

Lodder
  • 19,758
  • 10
  • 59
  • 100
  • Great! There are few things I'd like to clarify. According to the docs, the version is defined as `@version $Id: mod_XYZ.php 599 2010-03-20 23:26:33Z you $`. What is the significance of `$Id` and are the date and time manually entered or is there a way to auto create `@version` that is timestamped on the fly? – user1448031 Nov 12 '13 at 12:00
  • About the `$Id` and end `$`, I read somewhere that it's created by SVN. So I guess if I am not using SVN, then that's not applicable. Just using a version number like you've suggested should be good enough. – user1448031 Nov 14 '13 at 00:13