We have a page-level docblock like the following:
/**
* Functions for the processing, displaying, and searching of listings
*
* #package ListingFunctions
*
*/
The rest of the file has functions with their own docblocks. But my team and I can't find this comment anywhere in the generated HTML output. Is there some configuration or command-line stuff we need to turn on?
Using phpDocumentor 1.x, that "short description" piece should be the main description heading on the webpage for that given file. It won't appear on those functions in that file... just on the file itself. This is core behavior, that cannot be modified by runtime settings.
Related
I am using laravel. I need to know how phpdoc can be written in php 8 with attibutes.
/**
* Transform the resource into an array.
*
* #param \Illuminate\Http\Request $request
* #return array
*/
public function toArray($request)
{
//Some code
return [];
}
Can someone please explain how the above code can be written with attributes.
I believe you have misunderstood what Attributes are for, and how they related to doc blocks. There are two common uses of doc blocks (comments marked with /** ... */):
To document the code (hence the name "doc block"), in a mostly-standardised way which can be read by various tools, including documentation generators and IDEs.
To add machine-readable annotations to the code, for use with libraries and frameworks that can automatically generate behaviour based on those. For instance, an ORM might use an annotation of #TableName('Foo') to link a class to a particular database table, and generate appropriate SQL.
The example you've shown is of the first usage. What you have written is still the correct way of writing documentation.
PHP 8's native Attributes replace the second usage. It's up to the library what Attributes to look for, but an ORM that previously looked for #TableName('Foo') in a docblock might now look for #[TableName('Foo')] as a native Attribute instead.
There is a great automatic refractoring tool called rector. It will make your life so much easier. Install it, then create a rector.php file at the root directory that should look like something like this:
<?php
declare(strict_types=1);
use Rector\Config\RectorConfig;
use Rector\Doctrine\Set\DoctrineSetList;
use Rector\Symfony\Set\SensiolabsSetList;
use Rector\Symfony\Set\SymfonySetList;
return static function (RectorConfig $rectorConfig): void {
$rectorConfig->paths([
__DIR__ . '/src',
__DIR__ . '/tests'
]);
$rectorConfig->sets([
DoctrineSetList::ANNOTATIONS_TO_ATTRIBUTES,
SymfonySetList::ANNOTATIONS_TO_ATTRIBUTES,
SensiolabsSetList::FRAMEWORK_EXTRA_61,
]);
};
There are plenty of configuration options that you can find in the docs.
When you are done, just run the refractoring tool:
vendor/bin/rector process src
What (if any) tag can be used to specify a create and/or last modified date for PHPDocumentor? For example:
#created 2013-01-01
#author John Doe
#updated 2013-01-06
This is primarily for file-level DocBlocks.
Old question, but I was curious if there was a standard for adding a date to a docblock and found this question.
For my particular use case, I do use code versions/versioning, but I am the solo developer on a project so only I look at my code, and as my data is date based, I like to use a #introduced yyyy-mm-dd tag in my docblocks. Nice and easy to understand and I haven't got to hunt down when a particular tag was released. My code is version controlled, so I can look at line/function history, so I never add/change the date.
/**
* A brief description of the function
*
* #introduced 2020-06-24
* #return array
*/
public funcition hello()
{
return 'world';
}
I have a News section in my silverstripe site and I want to use the FulltextSeach functionality of Silverstripe:
FulltextSearchable::enable();
That works fine so far. But I´d like to have only NewsPages in my result. Is there a way to filter the search so that you get only certin pageType as a result for example?
Thanks in advance,
Chris
This is untested code but I've just had a look the source code of sapphire/search/FulltextSearchable.php
in mysite/_config.php you could add:
FulltextSearchable::enable(array());
which should remove the default searched classes which are SiteTree (all pages) and File
Then you can add an object extension in mysite/_config.php:
Object::add_extension('NewsPage', "FulltextSearchable('Title,MenuTitle,Content,MetaTitle,MetaDescription,MetaKeywords')");
Below is the comments from within the FulltextSearchable.php file
/**
* Enable the default configuration of MySQL full-text searching on the given data classes.
* It can be used to limit the searched classes, but not to add your own classes.
* For this purpose, please use {#link Object::add_extension()} directly:
* <code>
* Object::add_extension('MyObject', "FulltextSearchable('MySearchableField,'MyOtherField')");
* </code>
*
* Caution: This is a wrapper method that should only be used in _config.php,
* and only be called once in your code.
*
* #param Array $searchableClasses The extension will be applied to all DataObject subclasses
* listed here. Default: {#link SiteTree} and {#link File}.
*/
I'm using the tool from phpdoc.org and i'm stuck when I have a PHP file such as header.inc.php with only HTML inside.
<?php
/**
* Header content
*
* #author My name
*
* #since 1.0.0
*/
?>
<!DOCTYPE html>
<html lang="fr" class="no-js">
<head>
...
I get an error in my phpdoc "No page-level DocBlock was found in file...". I googled it but I didnt find any user with my case.
How to fix that error? Any tips are welcome.
Thank's!
Regards
I just ran across this posting and though it's older, I thought I would add my two cents. While sylouuu is correct about placing a namespace directly after the your intended page-level DocBlock, I believe that it is now required to place the '#package' tag in the DocBlock. There is some caution here when dealing with logical versus hierarchical 'packages'. This behavior is basically dependent upon which version of PHPDocumentor you are using.
From: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_elements.pkg.html
"In phpDocumentor version 1.2.2, a Page-level DocBlock is the first DocBlock in a file if it contains a #package tag."
And at https://github.com/phpDocumentor/phpDocumentor2/issues/910 it can be read that as recently as a month ago, the issue of page-level DocBlocks in files with no PHP code/nodes is still being worked. Thus, as sylouuu stated about adding a namespace, once you do this, you have an documentable element and your problem should be resolved. Additionally, since most likely no documentation for the page will be created without having a node present, this allows your html-only file to have its documentation created.
Hope it helps!
dw
Ok anwser found: https://github.com/phpDocumentor/phpDocumentor2/issues/695
TL;DR: At the moment, it's not fixed, just ignore theses warnings.
Some modules have a <request><direct_front_name>...</direct_front_name></request> in their module config, for example xmlconnect and api. What is this tag for?
What I think it is for:
xmlconnect and api are both used as direct entry points for the site (as opposed normal modules which are reached mostly from within the site). So in combination with the option to use store codes in your store urls you can specify a direct_front_end tag to make the store code not necessary for those modules. This way there is no 404 when calling them without a store code.
(Kind of answered it myself, but couldn't find any information about it online. Might be of use to others. And maybe anyone has something to add.)
You're totally right. And the php DOC clearly tells so :
Mage_Core_Controller_Request_Http::isDirectAccessFrontendName() :
/**
* Check if code declared as direct access frontend name
* this mean what this url can be used without store code
*
* #param string $code
* #return bool
*/
public function isDirectAccessFrontendName($code)