Jump to content

Software recommendations for documentation


NotionCommotion

Recommended Posts

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} []

 

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

Archived

This topic is now archived and is closed to further replies.

×
×
  • Create New...

Important Information

We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.