Clean up Core jsdoc

[gilesc50]

everything in core needs to be jsdocced, not all is
in jsdoc where a parameter can be 2 types use a pipe separator between them
for optional use [] and remove the words optional from the descriptive text