add doc comments to core file for the API