EzDevInfo.com

Rules to create file level @package

My code looks like this:

/**
 * @package Test
 */
require_once('foo.php');

/**
 * Main class
 */
class Test{
}

/**
 * Generic exception
 */
class Test_Excepcion extends Exception{
}

I want the first docblock to be a file level block, but ApiGen seems to link it to the require statement and my classes show up in the "None" namespace. It gets fixed if I do e.g. this:

/**
 * @package Test
 */
//
require_once('foo.php');

Is this the intended behaviour? Do I need to add a bogus comment after the file level block? What are the precise rules?

I can't install and run ApiGen

I'm creating a PHP micro-framework and decided to use ApiGen to generate the API. When I use the "apigen" command on terminal, I get the following message:

sh.exe": apigen: command not found.

Maybe it is the directory tree:

Project/
--Libraries/
----Attw/ (micro-framework and the directory to document)
----apigen/

What can I do? How can I organize the directory tree? And how can I execute the apigen correctly? I haven't found good tutorials about that.

API Gen with NetBeans 7.2.1

I cannot generate the documentation of my project. Getting the error message under NetBeans "'"php.exe"' is not recognized as an internal or external command, operable program or batch file.". The ApiGen 2.8.0 standalone has been unzipped in a separate folder and its reference is given under Tools->Options->apigen. Any advice from anyone? Thks in advance.

Using Apigen in Netbeans IDE

I have been trying to use the Apigen script to do documentation in Netbeans. I downloaded Apigen.phar file and created the Apigen.bat file. I added the location of it into the Netbeans in the Apigen section. When I try to do the documentation for the project I get the error below:

[InvalidArgumentException]
There are no commands defined in the "C" namespace.

Any suggestions please.

P.S: I am using Windows 8.1

Unable to install ApiGen using CLI

I am trying to install Apigen on windows. I am following instructions mentioned here.

But I am getting following error in cmd:

phpDocumentor / ApiGen @author tag location

I would love to post this as a general programming question. The reason I don't is that different documenting systems handle tags differently and therefore impose their own rules on what is "right" or "wrong" for a specific language.

Now the language in question is PHP. Which does not have a "standard" documentation system as of now. There is phpDocumentor, which while outdated as a project appears to have established the base. Current products like ApiGen seem to make an effort to support its syntax.

One tag I don't quite know where to put is the @author tag. I feel like placing it with the file level doc block. Together with @copyright, @license, @package and @link. Instead of inside the class level doc block. For some context: my PHP files contain one class declaration each only.

However, I failed to find the evidence supporting this to be an accepted standard. There is indeed little information to be found which location should be preferred. Which led me to believe that possibly I should include this information in both the file level doc block as well as the class level one.

Some examples: OpenEMR appears to prefer using @author both inside the file level block as well as the class level one (http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly). The document does not specify whether that is intended to happen at the same time or only if the file does not contain a class but rather a number of functions:

/**
 * library/sql_upgrade_fx.php Upgrading and patching functions of database.
 *
 * Functions to allow safe database modifications
 * during upgrading and patches.
 *
 * Copyright (C) 2008-2012 Rod Roark <rod@sunsetsystems.com>
 *
 * LICENSE: This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 3
 * of the License, or (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://opensource.org/licenses/gpl-license.php>;.
 *
 * @package OpenEMR
 * @author  Rod Roark <rod@sunsetsystems.com>
 * @author  Brady Miller <brady@sparmy.com>
 * @link    http://www.open-emr.org
 */

/**
 * inline tags demonstration
 *
 * This class generates bars using the main algorithm, which also 
 * works heavily with {@link foo()} to rule the world. If I want
 * to use the characters "{@link" in a docblock, I just use "{@}link."  If
 * I want the characters "{@*}" I use "{@}*}"
 *
 * @author ahobbit
 * @copyright middleearth.org XVII
 * @version 1.2.3
 */
class bar
{

}

The two projects referenced by ApiGen however (Doctrine ORM API and Nette API) don't seem to use the @author tag in the file level doc block but exclusively with the class level doc block. But then the only examples I saw when browsing where those including class declarations.

Doctrine is using @author along with other tags, I would have thought placing in the file level doc block, inside the class level doc block (http://www.doctrine-project.org/api/orm/2.4/source-class-Doctrine.ORM.AbstractQuery.html#AbstractQuery):

/**
 * Base contract for ORM queries. Base class for Query and NativeQuery.
 *
 * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @link    www.doctrine-project.org
 * @since   2.0
 * @version $Revision$
 * @author  Benjamin Eberlei <kontakt@beberlei.de>
 * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
 * @author  Jonathan Wage <jonwage@gmail.com>
 * @author  Roman Borschel <roman@code-factory.org>
 * @author  Konsta Vesterinen <kvesteri@cc.hut.fi>
 */
abstract class AbstractQuery
{ ... }

Nette, while also only using the @author tag in a class/interface context, does not appear to use @license @copyright or @link at all:

/**
 * Translator adapter.
 *
 * @author     David Grudl
 */
interface ITranslator
{...}

/**
 * Component is the base class for all components.
 *
 * Components are objects implementing IComponent. They has parent component and own name.
 *
 * @author     David Grudl
 *
 * @property-read string $name
 * @property-read IContainer|NULL $parent
 */
abstract class Component extends Nette\Object implements IComponent
{...}

How to prevent ApiGen from using fully-qualified names when replacing @link

We currently use ApiGen to document our PHP classes. Inside our doc comments, there are a lot of inline @link statements like this:

{@link AbstractValidatableItem}

When running ApiGen, the statement expands to a link like this (please ignore href):

\NSLevel1\NSLevel2\NSLevel3\AbstractValidatableItem

With many inline links, this creates an almost unreadable text. Therefore, I want to have a link with just the simple class, interface or method name:

AbstractValidatableItem

Is there any way to do this with ApiGen without patching it? I have already tried

{@link AbstractValidatableItem AbstractValidatableItem}

but this seems to break parsing of the link.

Handling Laravel's UserTrait with ApiGen

I've started using ApiGen with a Laravel project.

When I run it, I get the following error:

The class Illuminate\Auth\UserTrait is in use but has not been found in the defined sources.

Clearly it's complaining because Laravel's UserTrait isn't defined in the same file, but I obviously don't want to include my vendor/ directory and from the documentation I don't see how I can handle this. I want to use Jenkins to generate the documentation and because it returns a non-zero exit code it registers as an error, and thus breaks the build.

Here's my apigen.neon:

source:
    - app 

destination: docs

exclude:
    - "*/tests/*.php"
    - "*/database/*"

tree: true

sourceCode: true

todo: true

autocomplete:
    # default
    - classes
    - constants
    - functions
    # other
    - methods
    - properties
    - classconstants

title: My web app

Any idea how I can accomplish this?

How do I make an inline @link to another class in Apigen?

I'm trying to create a @link from one method to another method in a different class. Example:

class Bar extends Foo
{
    /** 
    * This link works: {@link barFunction()} 
    * This link also works: {@link fooFunction()}
    * This link doesn't work: {@link Foo::fooFunction()}
    */
    public function fooFunction()
    {

    }

    /**
    * Bar function is another function
    */
    public function barFunction()
    {

    }
}

The inline @link within the same class works OK. But the inline link to another class does not generate a link to the documentation. Instead, it generates:

<a rel='nofollow' href="Foo::fooFunction()">Foo::fooFunction()</a>

Am I doing something wrong or am I simply trying to achieve what is not possible? I looked over Apigen documentation and their forums (both at GitHub and Google Groups) but without any success. Thanks for your help.

When I try to run ApiGen I get a PHP Warning: require(Texy.php): failed to open stream: No such file or directory

I installed ApiGen successfully using the following commands:

pear channel-discover pear.apigen.org
pear channel-discover pear.nette.org
pear channel-discover pear.texy.info
pear channel-discover pear.kukulich.cz
pear channel-discover pear.andrewsville.cz

pear install apigen/ApiGen

Then I ran:

apigen -s /home/first.last/path/to/source/directory -d /home/first.last/path/to/destination/directory/

Only to get the following error:

PHP Warning:  require(Texy.php): failed to open stream: No such file or directory in /usr/bin/apigen on line 48
PHP Stack trace:
PHP   1. {main}() /usr/bin/apigen:0
PHP   2. class_exists('Texy') /usr/bin/apigen:64
PHP   3. spl_autoload_call('Texy') /usr/bin/apigen:64
PHP   4. ApiGen\{closure}($class = 'Texy') /usr/bin/apigen:0
PHP Fatal error:  require(): Failed opening required 'Texy.php' (include_path='.:/usr/share/pear:/usr/share/php') in /usr/bin/apigen on line 48
PHP Stack trace:
PHP   1. {main}() /usr/bin/apigen:0
PHP   2. class_exists('Texy') /usr/bin/apigen:64
PHP   3. spl_autoload_call('Texy') /usr/bin/apigen:64
PHP   4. ApiGen\{closure}($class = 'Texy') /usr/bin/apigen:0

When i ran

locate Texy.php

I got: (so clearly it's there)

/usr/share/pear/FSHL/Lexer/Texy.php
/usr/share/pear/FSHL/Lexer/Cache/Texy.php
/usr/share/pear/texy/src/Texy/Texy.php

How to make work in ApiGen

/**
 * Short desc
 * 
 * @param array $tabs
 * 
 * For example
 * <code>
 * $admin_tabs = array(
 *           'AdminDeliveryManager' => array('name' => 'Delivery manager', 'id_parent' => 0),
 *           'AdminRole' => array('name' => 'Admin role', 'id_parent' => -1),
 *           'AdminEmployeeRole' => array('name' => 'Admin role', 'id_parent' => -1)
 *       );
 * </code>
 * 
 * @return boolean true if all tabs created / false if have some error
 */