Joomla DocBlock header guidelines

Question

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?

Answer 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