Apidoc Improvments/Bugfixes

Yii 2.0 Extensions
1

I know it does not really belong in this subforum, but I did not find a better one.

I am considering fixing/extending some things in apidoc.

Despite it’s basically just a Yii-Thing, it’s currently one of the nicest generators.

I am not sure if I really have time to do everything (it’s just an attempt), but what’s the best approach to contribute?

Is it OK if I just enter a issue in bugtracker (without much details - just as a reference), create a branch named bug-xxxx and then make a pull request for the branch?

The main things I noticed so far is:

  • Current 2.1 does not work with PHP 7.1 nullable (?) returns (parser error). But this problem is gone when using 4.0 reflector
  • Types are ignored in documentation. It seems it just says “void” then
  • {@inheritDoc} shows {@inheritDoc} (at least with reflector 4.0)

And a few other things.

And it would also be nice to make it a bit more generally usable - e.g having a way to specify “extensions”. It could be even better be used for 3rdparty-stuff if apidoc did not just handle known official extensions as extensions, but having a way to specify “packages” somewhere in a configuration/parameter, so documentation can be split up.

But anyway: I cannot promise that I come far with these changes anyway (did not really analyze the real necessary effort). But I have a bit time left to try.

1 Like
2

Getting started document is here: https://github.com/yiisoft/yii2/blob/master/docs/internals/git-workflow.md

It is fine to just jump into it. apidoc is mainly creation of @cebe and he’s busy right now but I think myself and him will be able to answer questions if any.

3

I love the idea making apidoc a standalone tool that is good to use even for non-Yii projects.

1 Like
4

Ah ok, workflow as expected:

  • Break it up into issues and create them
  • make meaningfull branches for the issues
  • pull requests
5

Yes. apidoc is really a nice tool. If it was a bit more “open” it could be even more usable for extension/component developers and also for internal project documentation.

6

For now, I think, enhancing existing one makes sense. For the future we’ll consider making it standalone tool.

7

Yes, making it more configurable is probably one of the bigger changes. Fixing the few php compatibility flaws is probably more important.

And the standalone tool could even just use this one as library and extend.

The idea of making it more configurable is not at the top of the list. Trying to do everything at once often just breaks things.

1 Like
8

I could be great if the new Apidoc release merges this pull request:

I’ve been using it for almost two years and it works great. This is why I’m using my own fork since then.

9

@AndreasP How can you install phpdocumentor/reflection 4.0 along with a Yii 2 application? Composer complains “Your requirements could not be resolved to an installable set of packages.” if I try it.

10

@cebe apidoc needs your attention :wink:

1 Like
11

My modified version already works (quite) well with reflection 4 but it’s not a trivial change.

Internally phpdocumentor has completely changed it’s API. I use the approach “change as little as possible in apidoc, but as much as necessary”. Just changing composer requires unfortunately do not do the job.

Once I have the current functionality completely running again my plans are:

  • Add support for variadics
  • Add support for declared return types (I am going to merge them with the types specified in @return). My plan is to “change” the assumptions of phpdocumentor a bit: Currently apidoc assumes “void” if no @return is specified, but phpdocumentor assumies “Mixed”. So I am going to treat “mixed” reported by reflection as “void” unless it’s specified with in a @return tag.
  • Support for @property. Currently it automatically generates the properties from getXxxx and setXxxx methdos if the class is a subclass of BaseObject (which is a good thing). But additionally it should support properties just declared by @property.

More ideas?

1 Like
12

Great work!

13

What do you guys think: Should a declaration

“?\My\Class”

be displayed as type “null|My\Class” as traditionally used in docblocks or is the PHP syntax better?

Normalization of “?..” to “null|…” is possible, but it’s not possible to normalize the other way around.

14

Both syntaxes looks OK to me.

15

The fork is here:

It’s not finished, yet, but basically it works:

Changes:

  • Uses phpdocumentor/reflection 4
  • shows php variadics
  • Uses php 7 typehints
  • etc.

Known problem:

  • shows the FQSEN of a class twice for return types if it’s not fully qualified in the source
1 Like
16

Cool. How about a pull request?

1 Like
17

Will follow.

It’s still a bit buggy. The differences between in the reflection are big.

And a little rant about the now trendy “close classes”:

The new library version contains a lot of “final” stuff. It has places to hook in to customize, but there are not that many and a lot of stuff needs either copy&paste implementations or wrapper-classes.

Looking at it from the library user POV this pattern really turns into a develoopment nitemare quickly if just a litte detail needs to be extended, but there is nothing to hook in.