clarify intention of top level function
add top level ports property
correct note about filename convention