added JavaDocs for tuple-generating methods