Bug #83689

API Documentation for TYPO3 cms missing several public functions

Added by Sybille Peters about 1 year ago. Updated 7 months ago.

Status:
New
Priority:
Should have
Assignee:
-
Target version:
-
Start date:
2018-01-26
Due date:
% Done:

0%


Description

The TYPO3 api documentation for TYPO3 8 is missing several public functions.

Example 1:

The api for LocalizationFactory is missing the public function getParsedData.

The function is in the code.

Reproduce

I can reproduce this locally with

cd typo3_src-8.7.9/typo3/sysext/core/Classes/Localization
doxygen -s -g doxygen.cfg
doxygen doxygen.cfg

View file: html/classTYPO3_1_1CMS_1_1Core_1_1Localization_1_1LocalizationFactory.html

Cause of error

If the phpdoc

/** @var ... */ 

for $parser inside the try / catch block is removed, doxygen will include getParsedData in the generated docs
try {
  $this->store->setConfiguration($fileReference, $languageKey, $charset);
  /** @var $parser \TYPO3\CMS\Core\Localization\Parser\LocalizationParserInterface */
  $parser = $this->store->getParserInstance($fileReference);

see github LocalizationFactory

The problem is also reproducible if you change the order of variable name and type inside the phpdoc comment block, remove the variable name or change the type to 'string'.

AFAIK there is not really a standard way to document local variables inside of functions. @var is actually only for member functions, so maybe this is the problem. see

"Indicates that a comment block contains documentation for a variable or enum value (either global or as a member of a class)."

Solution 1

Change /** @var ... */ ... ? (I'm not sure if the core uses this internally).

Solution 2

Change doxygen configuration

HIDE_IN_BODY_DOCS = YES

api-structure.png View (49.9 KB) Sybille Peters, 2018-01-26 12:57

History

#1 Updated by Sybille Peters about 1 year ago

  • Description updated (diff)

#2 Updated by Sybille Peters about 1 year ago

More examples for missing public functions in API documentation for TYPO3 8:

They both contain a phpdoc comment with @var inside the function. If you remove that, the documentation for the function is created.

There's more, but I guess this should be enough information for now.

#3 Updated by Sybille Peters about 1 year ago

  • Subject changed from API Documentation for LocalizationFactory missing public function getParsedData to API Documentation for LocalizationFactory missing several public functions

#4 Updated by Sybille Peters about 1 year ago

  • Subject changed from API Documentation for LocalizationFactory missing several public functions to API Documentation for TYPO3 cms missing several public functions

#5 Updated by Sybille Peters about 1 year ago

In my test setting, a change in the configuration (doxygen.cfg) could remedy the problem:

HIDE_IN_BODY_DOCS = YES

http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_hide_in_body_docs

This will however cause any extra comments inside the functions to not appear in the API. However, since the API doc is typically about documenting the interfaces, it probably makes sense to hide the internal implementation anyway.

#6 Updated by Sybille Peters about 1 year ago

  • Description updated (diff)

#7 Updated by Sybille Peters about 1 year ago

  • Description updated (diff)

#8 Updated by Sybille Peters about 1 year ago

  • Description updated (diff)

#9 Updated by Stephan GroƟberndt 7 months ago

  • Description updated (diff)

#10 Updated by Sybille Peters 7 months ago

see thread on decisions.typo3.org about shutting down api.typo3.org: https://decisions.typo3.org/t/shut-down-api-typo3-org/355

Also available in: Atom PDF