Documenting Fusion

I miss the definition of a fusionDoc standard - documentation is important for reusability, and as many developers don’t read or write separate documentations :see_no_evil:, there should be a standard for Fusion like phpDoc for PHP.

there is Atomic Fusion Proptypes and I learned recently, this only works for Components but for everything else it could at least be used as documentation…

and when looking at the core Fusion prototypes, not every prototype has comments and when there are, only some properties are documented with comments in the fusion code but others are just documented in the docBlock of the PHP class - I think all the API properties/paths should be documented in the Fusion code

/**
* Render each item in items using itemRenderer.
*/
prototype(Neos.Fusion:Loop) {
 
  # The array or iterable to iterate over
  items = null
  items.@type = ${PropTypes.Iterable}

  # Context variable name for each item
  itemName = 'item'
  itemName.@type = ${PropTypes.string}

  # Context variable name for each item key, when working with array
  itemKey = 'itemKey'
  itemKey.@type = ${PropTypes.string}
}

if the above would not work or not be performant enough, it could also be written like that using the existing propTypes logic

/**
* Render each item in items using itemRenderer.
*/
prototype(Neos.Fusion:Loop) {

  # The array or iterable to iterate over
  items = null
  @propTypes.items = ${PropTypes.Iterable}

  # Context variable name for each item
  itemName = 'item'
  @propTypes.itemName = ${PropTypes.string}

  # Context variable name for each item key, when working with array
  itemKey = 'itemKey'
  @propTypes.itemKey = ${PropTypes.string}
}

eventually a Fusion reference could be compiled from the fusionDoc. :slight_smile:

2 Likes

about that proptypes dont work with anything else than components: i kickstarted the idea with runtime @type checks GitHub - mhsdesign/MhsDesign.FusionTypeHints

2 Likes

I just came up with that @type syntax myself, but it seems it is kind of intuitive. :grinning:

I really like the concept of propTypes to use Flow-Validators, because it is flexible and extensible. But I’ll have a deeper look at PropTypes and also the package you created.

But the formal type verification is only one part of my issue, the descriptions of prototypes and properties/paths are as important.

1 Like

I would really like to have an approach that allows us to generate the whole fusion prototype documentation automatically like for the eel helper docs. That would need descriptions for each property plus examples for the whole prototype in addition to the suggested @type. Problem is that this cannot be extracted from the parsed fusion anymore as all comments get lost during parsing.

I could imagine something like this:

/**
* 
*/
prototype(Neos.Fusion:Loop) {
  @description = "Render each item in items using itemRenderer." 
  
  items = null
  items.@type = "array|iterable"
  items.@description = "The array or iterable to iterate over"

With the @description beeing dropped in normal parsing and not beeing cached.

1 Like