0

I develop a custom triade component-module-plugin and I wonder how I have to properly enter comments.

What does @package and @subpackage mean? Is this somehow tied to how I pack my extensions for installation? Or is it used for some automatic docs build?

Should I use @package Joomla.Site or comehow name my extension here?

For example I copy mod_menu and change the comment to:

 * @package     Joomla.Site
 * @subpackage  mod_gruz_menu

Is this correct?

What about similar comments in plugins or component?

Please, explain or give a link to an explanation. Thank you.

1

The comment blocks that you see at the top, for example:

 * @package     Joomla.Site
 * @subpackage  mod_login

are simply the type that Joomla use to show that is the login module that part of Joomla core.

With your own custom extensions, you can use whatever you like. You don't have to put the subpackage there if you don't want to.

Some extension developers have their own preferred structure for the top comment block. Using the following for your own extension is perfectly fine:

<?php
/**
 * @package    My Extension Name
 * @copyright  Copyright (C) 2016 CompanyName. All rights reserved.
 * @license    GNU General Public License version 3, or later
 */

====

With 3rd party single extension, use @package for the name of your extension and don't use @subpackage.

If you have a pkg (package) that consist of a multiple extensions (component, module, etc), then use @subpackage as the name for each extension.

For example for a FrontEnd module

* @package Calendar.Site
* @subpackage mod_calendar

and for a backend component part

@package Calendar.Administrator
@subpackage com_calendar
  • So there are no any official recommendations on it, correct? And what can be the practical usage of these lines? – Gruz Aug 5 '16 at 16:39
  • Alas the link doesn't say much about what I ask about :-( I think if this link contains nothing, such an information doesn't exsists at all. – Gruz Aug 5 '16 at 21:04
  • It specifically says on that site which fields are optional and which are required – Lodder Aug 5 '16 at 21:13
  • This still doesn't answer in what cases and what @ package and @ subpackage I should have to use. It's clear how it's organized for core Joomla code itself, but not clear how it should be used for thirdparty extensions. I suspect correct comments may help to build nice autodocumentation for my extensions. But what is correct - not clear. – Gruz Aug 5 '16 at 22:43
2

According to https://developer.joomla.org/coding-standards/docblocks.html these comments are part of the DocBlock and are used by tools that generate documentation for code.

If you are writing your own extensions then you could completely omit these, providing your own copyright and licensing information as you see fit. However, following the standard and providing documentation blocks might help users of your extension troubleshoot their installation without bothering you, and may also help you if you extend your tooset to include something that can make use of such comments.

Specifically, @package is usually optional unless you only have procedural code in the file, i.e. no classes or namespaces. @subpackage is always optional.

For example, if you start the .php file with:

<?php
namespace MyMembershipMananger\com_Member\MemberDetailsEditor;

Then you would only need the `@since' from below

/**
  * @package     MyMembershipMananger
  * @subpackage  com_Member 
  * @since       0.0.01
  */

However, if you launched straight into a class declaration then you should provide all three.

Different styles of DocBlock are used for files, classes, and methods or functions.

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.