peej / phpdoctor Goto Github PK

classes/phpDoctor.php:1318
$tag =& new $class($name, $text, $root);

should be:
$tag =& new $class($text, $data, $root);

Hi,

I currently worked out a specification to make results of DocTools interoperable. This is completely new and the spec is just one day old. The idea of this spec is, that doctools deliver their output in this interoperable format and generating the output can be done by others, that don't want to work on the parsing part.

The benefits would be:

• End users can choose whatever doctool they want and which output generator they want.
• Doctool developers can focus on parsing the code, generate a standardised output and leave the output generation to the end users (doesn't that sound like less work for you?)

My blog post with my motivation for creating this: http://gos.si/blog/docspec-as-interoperable-file-format-between-doctools

As I said the DocSpec is not older than a day, you are invited to join here. Also if you feel like this idea suits your doctool, feel free to jump over to express your interesst in participating as an implementor.

The DocSpec is on github, ready to fork: https://github.com/gossi/docspec

Thank you
gossi

phpdoctor should include the original source code (optionally) in the output, annotated via e.g. GeSHi.

This would allow to link there from various places, e.g. from the all the places in the class documentation referring to the file.
Of course, this should include anchors for each line and those should get used where appropriate.

First of all, the generation does not work properly for me because of a problem in inheritDocTag.php on line 73...

PHP Fatal error: Call to a member function text() on a non-object in ...\phpdoctor\classes\inheritDocTag.php on line 73
PHP Stack trace:
PHP 1. {main}() D:\Downloads\phpdoctor\phpdoc.php:0
PHP 2. PHPDoctor->execute() D:\Downloads\phpdoctor\phpdoc.php:55
PHP 3. Standard->standard() D:\Downloads\phpdoctor\classes\phpDoctor.php:1139
PHP 4. ClassWriter->classWriter() D:\Downloads\phpdoctor\doclets\standard\standard.php:166
PHP 5. HTMLWriter->_processInlineTags() D:\Downloads\phpdoctor\doclets\standard\classWriter.php:190
PHP 6. InheritDocTag->text() D:\Downloads\phpdoctor\doclets\standard\htmlWriter.php:302

After this, I get a lot of HTML output and then the error again.

Fatal error: Call to a member function text() on a non-object in ...\phpdoctor\classes\inheritDocTag.php on line 73

Call Stack:
0.0006 335016 1. {main}() D:\Downloads\phpdoctor\phpdoc.php:0
59.7188 58986512 2. PHPDoctor->execute() D:\Downloads\phpdoctor\phpdoc.php:55
59.7291 59869920 3. Standard->standard() D:\Downloads\phpdoctor\classes\phpDoctor.php:1139
71.0484 59962832 4. ClassWriter->classWriter() D:\Downloads\phpdoctor\doclets\standard\standard.php:166
76.7687 60155936 5. HTMLWriter->_processInlineTags() D:\Downloads\phpdoctor\doclets\standard\classWriter.php:190
76.7692 60157608 6. InheritDocTag->text() D:\Downloads\phpdoctor\doclets\standard\htmlWriter.php:302

Not every class or interface is documented, some files are missing.
There are also some other problems i just noticed. If a class/interface is used somewhere, with the fact that it is not imported with the use-keyword because it is in the same package, and somewhere else a class/interface with the same name exists, then it can cause problems. This means in my special case, that there are two interfaces, blabla\cache\Cache and blublu\cache\Cache which are both used like that:

namespace blabla\cache;
class A implements Cache{...}

namespace blublu\cache;
class B implements Cache{...}

Now is the problem that the documentation site of class B is using blabla\cache\Cache and not the right one.

The next thing is, that when I allow different return/parameter types like a simple string and an OOP String like that:

@param \oop\String|string $value The string

Then it does not create a link to the class.

If a classes implement more that one interface, then only one is shown in the doc. Also the methods which these interfaces offer are not included.
If the inheritance is like that:

interface A{}

abstract class B implements A{}

class C extends B{}

Then in C is no documentatino about the interface A!

The field summary is formatted wrong, the left column gets about 50% of the width and this looks strange. I don't know if a link is created to the class doc for throws annotations but in the old version it is not.

A nice feature would be if classes which implement interfaces are mentioned in the doc of the interfaces, this would be more java like with links:

Direct Known Subclasses/Implementations ...

Interfaces are recognized during the doc generation and shown in the navigation, which is fine. They are not connected from the classes that implement them and vice versa. So:
class A implements MyInterface
In Javadoc this connection is shown on the class page. Saying this class implements these interfaces.
On the other side, Javadoc displays "All known implementing Classes" on each Interface.

In CodeIgniter there is a function named set_select which has the following docblock:

 /**
  * Set Select
  *
  * Let's you set the selected value of a <select> menu via data in the POST array.
  * If Form Validation is active it retrieves the info from the validation class
  *
  * @access public
  * @param  string
  * @param  string
  * @param  bool
  * @return string
  */

When I view the index for my documentation, I can only get to elements that alphabetically precede set_select, because phpdoctor parses that select tag and then stops output. This is all I see:

  set_select() - Function in package GiftFlow
     Set Select Let's you set the selected value of a  [[ DISPLAYS SELECT DROPDOWN HERE]]

Would be cool to see in the generated docs, which classes resp. interfaces are descendents of my currently viewed class/interface (similar to javadoc)

There is no rule reducting parent directory (../) in makeAbsolutePath() method.

for instance,
source_path = "../code"
will be transformed in "/(path)/.code/" because of the final str_replace();

class constants are "documented" as final variables - which at least as of php 5.3 (static binding) is not correct...

class constants of type boolean get documented as "mixed" (always wrong for constants), while integer constants get "int" (correct).

Some constants - I didn't find a pattern yet - get documented with a preceding dollar sign; although NO instance with dollar sign is found in the sources.

Given that one of the major additions to PHP 5.4 will be Traits (see http://www.php.net/archive/2011.php#id2011-06-28-1), and as the syntax has been pretty much set in an RFC, PHPDoctor should support them.

Whenever I try to generate my documentation for this project: https://github.com/paullik/yaCMS

I get the following error:
https://gist.github.com/1069566

I get that error just for my project, if I try to generate docs for your cloned phpdoctor it works well.
Here's my config: https://gist.github.com/1069578

The command I run: php phpdoc.php yacms.ini

PS:
This happens in both cases(if I use the archive or git clone)

With current Git I'm getting a lot of the following notices:

[...]
Writing "source/blogs/htsrv/async.php.html"
PHP Fatal error: Call to a member function containingPackage() on a non-object in /path/to/phpdoctor/classes/seeTag.php on line 79
PHP Stack trace:
PHP 1. {main}() /path/to/phpdoctor/phpdoc.php:0
PHP 2. PHPDoctor->execute() /path/to/phpdoctor/phpdoc.php:53
PHP 3. Standard->standard() /path/to/phpdoctor/classes/phpDoctor.php:1040
PHP 4. SourceWriter->sourceWriter() /path/to/phpdoctor/doclets/standard/standard.php:179
PHP 5. HTMLWriter->_processInlineTags() /path/to/phpdoctor/doclets/standard/sourceWriter.php:100
PHP 6. LinkTag->text() /path/to/phpdoctor/doclets/standard/htmlWriter.php:298
PHP 7. SeeTag->text() /path/to/phpdoctor/classes/linkTag.php:49

It would be really nice if you could add an throws-clause to the methods docblock. Then it would be more clear where to use a try-catch.

When included code contains HTML (eg in global variable), it is not properly escaped.

For example following HTML is generated:

<code class="signature">public  mixed <strong>str_export1</strong> = '<select name="export_type"><option value="sqldumpfile">' . __('SQL dump (file download)'

JavaDoc uses the documentation of the next super class/interface where a doc is available if no documentation is made for an implemented or overridden method, but does not do that!

See this answer: http://stackoverflow.com/questions/3401642/how-do-i-make-javadoc-inheritance-work-for-external-apis-with-maven2

Because of the possibility to use __callStatic or __call, there should be a @method annotation which allows the developer to document these things.
In addition to that, @Property(-read/-write) should be included into the fields table with the keyword final if only read access is allowed and for write only something else. Write only for a property is bad practise, but PHP offers you that possibility...

Here is a short list of features I am missing in phpdoctor:

• General: Allow source path to be relative to the ini path
• General: Allow @access to overwrite the given modifier -> check if $currentData['access'] is already set(~near at line 655)
• Class Doc: Show all implemented interfaces
• Class Doc: Show direct known subclasses
• Class Doc: Link to the class in the "Methods inherited from class ..."-table
• Interface Doc: Show all known implementing classes
• Interface Doc: All known subinterfaces
• Interface Doc: All superinterfaces

For some reason having more than one class constant in a class causes this error for me.

Fatal error: Call to undefined method RootDoc::packageName() in (...)/classes/phpDoctor.php on line 877

The bug only appears when the class is in a namespace

In the constructor of phpDoctor the configuration option should get stored into the properties $_tagletPath and $_docletPath.

PHPDocumentor supports page-level documentation blocks, which describe the file itself, not the element following it.
In recent PHPDocumentor versions the logic to detect those is: first comment containing a @Package tag documents the file.

I would like to see support for this with phpdoctor, too.
At least it should be possible to not have those page-level blocks get assigned/used for the first var following it.

On Fedora Linux, I'm trying to run PHPDoctor on a very large code base. It's hitting a fatal error when it runs out of memory at 1GB. This is odd, because I've given it 5GB in php.ini and with an inline set_ini('memory_limit','5120M'), and if I add phpinfo() to the top of phpdoc.php, it claims it has 5120M available. I don't see anything in its own .ini file that sets a limit.

It may turn out that I don't have enough RAM to throw at it to run on our whole code base, but first I want to see what it can do with 5GB. Any ideas?

Hello,

I also have come from PhpDocumentor and I like to use the @todo tag in my code for reminding myself what to do. In PhpDocumentor this creates a single todo page but phpdoctor doesn't seem to support it yet. I would think to create an HTML file like readme.html that would show up under the All Items link will be perfect.

Thanks.

Small feature request, document class member variables:

class Class1
{
    /** Documentation on member variable */
    string var;
};

PHPDoctor needs a PEAR package for easy installation. I think this would help the adoption of PHPDoctor.

Steps to reproduce (Unix):

1. clone phpdoctor somewhere on your maching.
2. cd /path/to/phpdoctor
3. chmod +x phpdoc.php
4. Add phpdoc.php to the environment path variable
   (I have a private bin directory from which I've created a symlink to /path/to/phpdoc.php
5. cd /path/to/project
6. Execute: phpdoc.php phpdoc.ini

Expected results:
phpdoctor should run

Actual results:

The following error is encountered:

PHP Warning:  require(classes/doc.php): failed to open stream: No such file or directory in /home/pgraham/projects/phpdoctor/classes/phpDoctor.php on line 40
PHP Fatal error:  require(): Failed opening required 'classes/doc.php' (include_path='.:/usr/share/php:/usr/share/pear:/home/pgraham/bin') in /home/pgraham/projects/phpdoctor/classes/phpDoctor.php on line 40

Patch:

The fix is pretty simple so I've included the diff here but if you prefer I can fork and make a Pull Request.

--- a/phpdoc.php
+++ b/phpdoc.php
@@ -32,7 +32,7 @@
 if (!isset($argv[0])) {
 }

 // include PHPDoctor class
-set_include_path(get_include_path() . PATH_SEPARATOR . dirname($argv[0]));
+set_include_path(get_include_path() . PATH_SEPARATOR . dirname(__FILE__));
 require('classes'.DIRECTORY_SEPARATOR.'phpDoctor.php');

 // get name of config file to use

Hi,

I use __construct method for my constructors.
If arguments of a constructor defined in sub class are different from parent class,
the parent's constructor still gets documented in the sub class.
Could you change that please?

Thanks

@access private Should exclude methods, this currently only works on fields.

This is very usefull if I want to exclude something as: __uglyPrivateFunctionName($with, $to, $much, $parameters)

Hi there,

I think it would be good to be able to enable/disable file level comments.
All of my source files do have a licence text as first comment. That means it will be taken as file level commment.
The result is that phpdoc tries to process each file twice - once with the package as per @Package on the actual code and then again with a package based on the file path.
Beside being annoying the second run fails as the path is not created and this the htmlWriter fails to write and phpdoc exists with error.

Actually, this happens even if I remove the special code that looks at the first comment ($commentNumner == 1)

Although the website mentions the @see parameter phpdoctor seems to completely ignore it. I would expect this parameters to be parsed in such a way that I can click it in the documentation to go to the related method / class. The same goes for @return.

Is this still a planned feature, am I missing a configuration directive or is this simply not being implemented?

Thanks

I think we've discussed this a long time ago, but I can't find the docs any more.
My project uses @inheritdoc quite a lot (which looks not that great in the docs right now), so I think it's time to give that a go again.
From what I can gather the tag is supposed to be replaced by the parent class doc. In addition, there can be new comments/doc beside the @inheritdoc tag.
If yo could give me a few pointers where to start I'd be happy to give that a go

It seems that methods that have an underscore as the 1st character of its name doesn't appear in the generated doc.

I used tho named some of my methods like that :

public function _redirect_to($destination)
{
}

but phpdoctor doesn't generate the documentation for them.

Is it a bug or am I missing something ?

Regards,
Steph.

We are now running PHPDoctor as a nightly cron job on our code base. Since it's large, this takes several hours.

One neat feature would be the ability to say "only regenerate documentation for files that git shows as changed."

I realize this would be complicated - you'd have to store a record of parent-child class relationships on disk, I imagine - but I thought I'd mention the idea.

My code repository is located at:

/usr/local/www/domain.com/subdomain./htdocs/mycode/

The issue occurs in that when phpDoctor attempts to resolve this path, it ends up mangling it and errors out as the directory no longer exists (and my account does not have permission to write to the generated one).

The issue seems to occur with line 471 in classes/phpDoctor.php:

$absPath = str_replace('./', '', $absPath);

Which causes the folder to resolve to:

/usr/local/www/domain.com/subdomainhtdocs/mycode/

I have commented the line out and it is working for me just fine, but I'm not sure why it was there in the first place, so I do not know exactly what side-effects this would have, or what the line was trying to accomplish in the first place (to attempt to resolve the issue in a way that does not cause issues with some other type of path) - otherwise I'd just submit a patch.

Other than that everything seems to be working for me! :)

The @Package tag should IMHO consume just one line and not follow to next lines.

Sample:

/**
* @package JAMA
* 
* Error handling
* @author Michael Bommarito
* @version 01292005
*/

This should create package JAMA with file comment Error handling.

Many of our classes do not yet have packages assigned, but all of them have unique names based on the code's directory structure, like "class Somedir_Subdir_Classname". For us, it would be ideal if the documentation fell into the same directory structure instead of "packagename/classname." Besides which, using the package name in the URL means that the URL will change as we add @Package information in the future.

1. Would customizing this require changing code in many places, or just classWriter?
2. Would you consider making URL path a config option, or would we have to branch the code to do this?

Hi there,
I've tried various ways of formatting code examples (

, ), but none seem to be working really well.

seems to be somewhat ok, however lines seem to be getting trimmed somewhere, so indentation gets lost.
is there a recommended way or would that be a new feature?