[TYPO3-hci] Documenting Typoscript

[Jeff Segars]

In the list for the Extension Coordination Team, we've been having a 
little discussion on inline documentation for Typoscript.  Kasper 
suggested we move the discussion here as a usablity improvement for 
developers in 4.5.....

Jeff Segars wrote:
> Since this seems to by Typoscript day around the ECT newsgroup (thanks 
> Elmar!), I figured I'd make a post that I've been thinking about for a 
> while.
> 
> In helping with documentation for the Calendar Base extension, I've been 
> reminded again how painful it is to provide good documentation for 
> Typoscript within an extension manual.  Making sure every option is 
> covered is a pain and the challenges only increase when many people are 
> working on the code.
> 
> I've talked to several people about inline, javadoc-like documentation 
> for Typoscript, with the goal of parsing the TS and generating reference 
> tables more automatically.  The constant editor already takes a step int 
> this direction with its fields, but we'd likely need something a little 
> more robust.
> 
> Has anyone else given any thought to standardizing inline documentation 
> for Typoscript in order to pull it up to higher level documentation?
> 
> Thanks,
> Jeff


Kasper Skårhøj wrote:
> Looking forward at version 4.5 I think it could be _the_ usability 
> improvement for developers if _all_ TypoScript could be validated and 
> documented inline:
> 
> - Any TypoScript configuration (TS templates/TSconfig) is "somehow" 
> defined in the actual code and can be extracted from there by some viewer.
> - Semantics are fixed without this definition so that any TypoScript can 
> be validated!
> As a consequence:
> - All TypoScript documentation (TSref/TSconfig/Extension documents with 
> tables) is removed because its obsolete. Documentation is completely 
> inline in TYPO3, depends exactly on what extensions are installed and it 
> all validates so no more guesswork!
> 
> 
> So, now its time to go to the HCI team and suggestion this!
> 
> - kasper