SPARK-3278 added comments and cleaned up api to consistently handle weights