Recent searches
Search options
I'm going to try to reboot the working group for @phpfig's psr-5. Goal is to write down the standards we are already using in @phpstan @phpdoc @phpstorm, @psalm and many others.
I'm looking for people that will help me once in a while to check if I do not write down things that will break these amazing tools.
My goal of #psr5 is to provide a definition of a docblock in a way people can write their own parser. We do keep the standard as open as possible.
We should not block innovation with standards. But allow others to follow the standard by implementing their own parser. This project has been dragging for a very long time. And I truly believe that #php needs a standard for docblocks.
Everyone will benefit from this and it will increase the user base of our loved tools. As they will simply work next to each other
@jaapio is it worth getting rid of docblocks for attributes overall?
Or is it more standardisation of what is already in use?
@ocramius just standardize what is already in use. This will open doors to start a discussion for more. But I don't think anyone is waiting for a new standard written by me. Adoption will be an issue for a new standard.
@bobmagicii maybe, but why introduce a new standard when everyone is using the old one? standards describe what you already use. It's not my goal to invent something new. There are more fun things to invent than a documentation standard.
If we write down that you should use attributes.. who will use that if non of the tools supports it? No matter how good the idea might be. It all starts with adoption. There are enough stories in tech that explain exactly that.
@jaapio @bobmagicii @ocramius Many previous uses of docblocks have turned into attributes, and that's good. But I wouldn't make `@return`, `@see`, `@link`, `@author`, etc. into attributes, nor the short and long descriptions of an element. Both still have their place, just better separated now.
@bobmagicii @jaapio @ocramius @link Right up until you want to specify a type that PHP cannot represent natively.
Or you need to provide a human-readable description. PHP can't do that natively.
PHP's type improvements make docblocks much *less* necessary than they were in the past, but as long as humans read code, it will never be zero. (True in any language.)
@bobmagicii recommended to use native types over docblocks for sure! But sometimes... You can't use types. We have been in this situation. And we will be again.
@jaapio @bobmagicii @Crell @ocramius @link fwiw I think using Attributes for generic types etc would be awkward at best and if you have "string" attribute types #Type('Foo<array<string,string>,Blah<Boo>>') then you still need a type parser (and maybe THAT can be separately standardised?). I can't see docblocks beginning to go anywhere until we have native generics :)
@dantleech @jaapio @bobmagicii @ocramius There are ways it could be done, but they'd all be pretty awkward.
#[Map(key: 'string', value: new Seq(type: Boo::class))]
@jaapio A docblock standard I think would be a good idea for PHP. I feel like JUnit set the standard years ago, and PHP hasn’t really updated things.
Some people might argue that docblocks are becoming less relevant due to the use of stronger and improved typing at the language level.
What kind of innovation would you like to see in doc blocks?
@awoodsnet I think docblocks are still relevant fora use cases php doesn't support native. Examples are generics and callables that cannot be documented nor specified. You could argue that we should add those to the language but we already have alternatives in user land. And sometimes with conflicting interpretations.
A well defined standard should make it easier for new tools to add their own tags without interfering with existing tools.