Documenting Fusion

Altough the voting was in favour of the comment syntax by a few votes, for me it just doesn’t feel right to use comments for typehinting in fusion when we just got rid of that (anti) pattern in PHP… :neutral_face:

And we even have the meta properties as language construct to handle the type hints with the existing parser. If we want to introduce types in Fusion, I think they should be part of the syntax from the beginning and not be put in comments.

1 Like

I see where you are coming from, as the first idea was to leverage the existing @propTypes etc.

But I want to state again that /// would not be a comment but a documentation statement. So it is as much of a comment as the #[Attribute] is in php.

I am pretty sure we have a working fusion formatter/prettier before we get a final implementation of types in fusion so when the time comes we can automatically extract every type from documentation statements into @type or however it will look like then.

In the future the parser can put it as documentation into __meta for example.

So for now we would use the documentation statements for what they are and in the future they will be a shorthand for @doc.

Maybe we could come up with a slightly different syntax that is not as easily confused with comments?

Even if i am a bit pedantic about /// not being a comment…it would still be parsed as a comment in most of the currently deployed fusion parsers :smile: And as “normal” comments are most of the time documentation anyway /// would just make “official” documentation out of comments

So people can start using the documentation now. Without any updates.

Do you have an idea for a different syntax?
(Maybe -- This is documentation ? But then would we just use another comment syntax :smile: )

I btw. now started using the /// annotations for my components in the new Neos.Workspace.Ui PR FEATURE: New workspace overview UX by Sebobo · Pull Request #5132 · neos/neos-development-collection · GitHub

I definitely miss the propTypes validation and I don’t want to do both in the same file. But it still helps me a bit, to make more sense of what I’m doing (especially as I’m sick since last week again :face_with_thermometer: ).

My feelings for the 3 dashes already changed a bit in the last few days. At first it felt wrong, and today I actually didn’t care anymore for the most part.
As soon as I get highlighting (sadly can’t combine Simons TextMate bundle with the Neos plugin in PHPStorm) and can navigate to the class from the annotation, I would be pretty happy.