Type…hinting
I vouch strongly for keeping type information in the documentation as it is needed to fulfil the main goal…the substitution of the hardcoded Neos Fusion Reference.
But i think we should call them type hints from now on and everywhere :D just to make sure they are not understood as “real” types…So i vouch for keeping the type hints.
/// or #
Using # for the documentation was an idea as well. But that would mean to completely change the usage of an existing token which is not ideal.
/// stems from Rust where it is already used for documentation. (and i personally do not like the # comments but that would be too opinionated to even mention it sooo…)
/// also follows the same idea as the PHP attributes #[foo] where an existing single line comment has another completely different meaning because of its next character.
So conceptional /// is not a "single line comment token with a following / ". It is the “property documentation token” and /** & **/ are not a “multiline start and end tokens” but “prototype documentation start and end tokens”. Just by a “great coincidence” the existing fusion parser interprets them as comments. Or should i say the existing fusion parser implementation interprets them as comments? …foreshadowing…
Even better ?
@Marc and i tested a few other ideas like using ```doc or /*doc for prototype docs etc. but they all seemed too clunky to write and looked kinda weird.
But if there are any other ideas please feel free to throw them into discussion!
Next steps
Currently my favourite is using /// and /** **/ instead of @types and @doc. With proper syntax highlighting the code looks like a document which you can read. It is easier to parse visually. It just looks nice.
prototype(Foo.Bar) {
/// string The title above the text
title = "bar"
}
But if we would use @typeHints instead of @types we would not make false promises and do not a give false sense of (type) safety:
prototype(Foo.Bar) {
title = "bar"
@typeHints.title = "string"
@doc.title = "The title above the text"
}
OR…because no abbreviations…
prototype(Foo.Bar) {
title = "bar"
@typeHints.title = "string"
@documentation.title = "The title above the text"
}
So when we would introduce “real” type a simple search @typeHints & replace with @types would be quite nice.
End note
Would it make sense to start a vote between the general idea of using something like /// and using something like @doc ?
Because where the data of @doc gets stored (in _meta or in _documentation) or if we use # instead of /// are subtleties in my opinion.
Everything after /// (or #) would not be text but its own very small documentation language and where or even if that is stored has nothing to do with how it is written. The same goes for @doc. Both of them could land inside _documentation in the merged array tree or not at all.
The general idea is to separate language specification from implementation. The specification can be opinionated by the implementation of course…but still.
A future specification could introduce “real” types and /// would then be used only for text:
prototype(Foo.Bar) {
/// The title above the text
title: string = "bar"
}
visually easy to read and understand when viewing the sources
documentation syntax (if not validated strictly) is in complex cases try and error and thus a bad dx
requires adjustment on the parser who should generate the RST docs - doesnt have to be in php land as we can also extend Simons javascript fusion parser.