PHP Doc @example example

Question

I'm integrating PHP doc with my product since I plan to allow users to change various things inside the plugin.

So far so good, I have phpdoc .phar in my directory and I can parse the html files. But I have two issues:

1 - I can't figure out how exactly to use the @example tag,

Here's my code:

/**
     * Creates a custom cron schedule.
     * @param array $schedules list of schedules
     * @example class-wcdpue-admin.php add_filter( 'wcdpue_custom_cron_schedule', 300 ); Creates a custom cron
     * @since    2.0.0
     */
    public function wcdpue_custom_cron_schedule( $schedules ){

        $schedules['wcdpue_cron'] = array(

            'interval' => apply_filters( 'wcdpue_custom_cron_schedule', 900 ),
            'display' => __( 'Every 15 Minutes' )

        );

        return $schedules;

    }

When I check phpdoc it shows like this:

I'm not certain why it says the file is not found but I can't find an example online for using this tag, I was expecting it to show a little code box with my example of usage.

2 - How do I fix the file not found issue?

The class file path is oop/admin/class-wcdpue-admin.php and I have tried changing the doc block to:

/**
         * Creates a custom cron schedule.
         * @param array $schedules list of schedules
         * @example /admin/class-wcdpue-admin.php add_filter( 'wcdpue_custom_cron_schedule', 300 ); Creates a custom cron
         * @since    2.0.0
         */
        public function wcdpue_custom_cron_schedule( $schedules ){
    
            $schedules['wcdpue_cron'] = array(
    
                'interval' => apply_filters( 'wcdpue_custom_cron_schedule', 900 ),
                'display' => __( 'Every 15 Minutes' )
    
            );
    
            return $schedules;
    
        }

The phpdoc command I am running is: php phpDocumentor.phar -d oop/ -t docs/api --sourcecode if it's of any help I also can't see source code from the rendered phpdoc for any of my defined blocks for some reason:

Any help is appreciated

Answer 1

@example Specifies the path to a file containing the example code usage. phpDocumentor will publish the example with syntax highlighting and line numbers.

For example: @example /path/example.php description

Answer 2

Using phpDocumentor 3.4.2, I have the same issue. I tried:

@example "/fullpath/file.php" Description

And the generated documentation is:

Tags 
example
"/fullpath/file.php" Description

But according to the official documentation:

The effects of this tag are not yet fully implemented in phpDocumentor 3.