Software recommendations for documentation

[NotionCommotion]

I previously used https://www.phpdoc.org/ (not sure about the part 2 part) but got out of the habit.  Wish to change, but had more installation problems than expected.  Is it still considered a good solution?  If so, any recommendations whether I should install using pear, phar, or other?  Thanks

[requinix]

phpDoc is about code documentation. Classes and functions and such. Works fairly well for that. For things that aren't just about code, I like Markdown and wikis.

PEAR and PHAR have nothing to do with this.

[NotionCommotion]

8 hours ago, requinix said:

phpDoc is about code documentation. Classes and functions and such. Works fairly well for that.

Do you know whether phpDoc will reflect PHP's argument and return type declarations, or whether this must be duplicated using phpDoc tags? If not, do you know of any documentation applications that do?

 

8 hours ago, requinix said:

PEAR and PHAR have nothing to do with this.

http://docs.phpdoc.org/getting-started/installing.html states that phpDoc can be installed using PEAR, PHAR, or using Composer (where Composer is advised not to do).  I installed with no immediate problems using PEAR.

$ pear channel-discover pear.phpdoc.org
$ pear install phpdoc/phpDocumentor

But then I found that most of my scripts were not included in the phpDoc created website.  So, I made a test directory with the single file below in hopes of identifying the problem.  First it outputs that I don't have a file summary and $myArgument is missing which surprises me as the test file came directly from http://docs.phpdoc.org/getting-started/your-first-set-of-documentation.html.  The it complains a couple times about array to string conversion and undefined properties and eventually halts with a fatal error.

Any thoughts?

 <?php
 /**
  * A summary informing the user what the associated element does.
  *
  * A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
  * and to provide some background information or textual references.
  *
  * @param string $myArgument With a *description* of this argument, these may also
  *    span multiple lines.
  *
  * @return void
  */
  function myFunction($myArgument)
  {
  }

[michael@devserver phpdoc]$ phpdoc -d src -t doc
Collecting files .. OK
Initializing parser .. OK
Parsing files
Parsing /home/michael/phpdoc/src/Example.php
  No summary was found for this file
  Argument $myArgument is missing from the Docblock of myFunction
Storing cache in "/home/michael/phpdoc/doc" .. OK
Load cache                                                         ..    0.001s
Preparing template "clean"                                         ..    0.007s
Preparing 17 transformations                                       ..    0.000s
Build "elements" index                                             ..    0.000s
Replace textual FQCNs with object aliases                          ..    0.000s
Resolve @link and @see tags in descriptions                        ..    0.000s
Enriches inline example tags with their sources                    ..    0.000s
Build "packages" index                                             ..    0.000s
Build "namespaces" index and add namespaces to "elements"          ..    0.000s
Collect all markers embedded in tags                               ..    0.000s
Transform analyzed project into artifacts                          ..
Applying 17 transformations
  Initialize writer "phpDocumentor\Plugin\Core\Transformer\Writer\FileIo"
  Initialize writer "phpDocumentor\Plugin\Twig\Writer\Twig"
  Initialize writer "phpDocumentor\Plugin\Graphs\Writer\Graph"
  Execute transformation using writer "FileIo"
  Execute transformation using writer "FileIo"
  Execute transformation using writer "FileIo"
  Execute transformation using writer "FileIo"
  Execute transformation using writer "FileIo"
  Execute transformation using writer "twig"
PHP Notice:  Array to string conversion in /usr/share/pear/phpDocumentor/vendor/erusev/parsedown/Parsedown.php on line 894
PHP Notice:  Undefined property: Parsedown::$Array in /usr/share/pear/phpDocumentor/vendor/erusev/parsedown/Parsedown.php on line 894
PHP Fatal error:  Uncaught TypeError: Argument 1 passed to Monolog\ErrorHandler::handleException() must be an instance of Exception, instance of Error given in /usr/share/pear/phpDocumentor/vendor/monolog/monolog/src/Monolog/ErrorHandler.php:122
Stack trace:
#0 [internal function]: Monolog\ErrorHandler->handleException(Object(Error))
#1 {main}
  thrown in /usr/share/pear/phpDocumentor/vendor/monolog/monolog/src/Monolog/ErrorHandler.php on line 122
[2019-01-27 12:04:42] phpDocumentor.ALERT: Fatal Error (E_ERROR): Uncaught TypeError: Argument 1 passed to Monolog\ErrorHandler::handleException() must be an instance of Exception, instance of Error given in /usr/share/pear/phpDocumentor/vendor/monolog/monolog/src/Monolog/ErrorHandler.php:122 Stack trace: #0 [internal function]: Monolog\ErrorHandler->handleException(Object(Error)) #1 {main}   thrown {"file":"/usr/share/pear/phpDocumentor/vendor/monolog/monolog/src/Monolog/ErrorHandler.php","line":122} []

 

[kicken]

Try using the phar file instead of through pear.  Worked ok for me when I tried it.

 

[requinix]

9 hours ago, NotionCommotion said:

Do you know whether phpDoc will reflect PHP's argument and return type declarations, or whether this must be duplicated using phpDoc tags? If not, do you know of any documentation applications that do?

I don't know, but I would expect that phpDoc would pick up on type hints when there aren't docblocks. But you should write those docblocks - your life will be noticeably easier if your IDE can give you more information about the functions and methods you're trying to call.

[NotionCommotion]

4 hours ago, kicken said:

Try using the phar file instead of through pear.  Worked ok for me when I tried it.

 

Yes, I tried as well and it did work for me as well.

My next objective is being able to invoke phpDoc within a PHP application to parse the given directory and return the output.  The end goal is a page which lists my various projects with links to the documentation action buttons to parse a given application.

I can use the phar file from the command line by executing usr/bin/php /usr/share/phar/phpDocumentor.phar -d myDir -t myTarget.  I suppose I can wrap it in a shell script and call it using shell_exec(), but that seems kind of convoluted.  Placing include '/usr/share/phar/phpDocumentor.phar'; in my script doesn't make sense as I am not providing the arguments or capturing the output, but I think something along these lines might be the best way to do it.

Trying to use Composer and locating it in vendors resulted in a bunch of dependency objections and appears to be more trouble than it is worth.  Trying to use the source code also resulted in autoloader problems.

Any thoughts?  Thanks

[NotionCommotion]

1 hour ago, requinix said:

I don't know, but I would expect that phpDoc would pick up on type hints when there aren't docblocks. But you should write those docblocks - your life will be noticeably easier if your IDE can give you more information about the functions and methods you're trying to call.

Yes, I've discovered that phpDoc does do so.  The IDE already gives some information if the arguments/returned value is type declared but there is obviously more phpDoc tags available.

[kicken]

33 minutes ago, NotionCommotion said:

My next objective is being able to invoke phpDoc within a PHP application to parse the given directory and return the output. 

Just use exec() to run the same command you'd run on the command line.

exec('/usr/bin/php /usr/share/phar/phpDocumentor.phar -d myDir -t myTarget');

If you need your directory and target to be dynamic use variables and escape them properly.

[NotionCommotion]

Thanks kicken,  In progress of doing just that, and it seems like the way to go.