CommonTakeAndDropDocs and CommonTakeAndDropWhileDocs hold the common docs for drop and take.
1. @return is inverted for the drop* functions
The generated @return is correct for take, but not for drop.
Following the templates, the KDocs for the operations from drop.kt say:
Returns: A `ColumnSet` containing the first/last [`n`] columns.
But for the drop* operations it is the other way around: they return everything except those columns.
Suggestion: add a RETURN key to both templates, set separately from take.kt and drop.kt, or a smaller variable for the containing / without part (by @Jolanrensen).
2. *While docs don't say that the run stops at the first non-matching column
For dropWhile/dropColsWhile/dropLastWhile/dropLastColsWhile, the KDocs say:
"This function drops the first/last columns from this adhering to the given predicate collecting
the result into a ColumnSet."
It might not be obvious to the reader that dropping stops with the first element that does not adhere to the predicate (and it is not like "take/drop the first/last n columns).
Suggestion: the meaning would be clearer if the KDocs mentioned something like:
This function keeps dropping the first/last columns from [this] and stops once the given predicate does not hold... (by @Jolanrensen).
The same goes for takeWhile/takeColsWhile/takeLastWhile/takeLastColsWhile
3. drop(Last) and take(Last) on DataColumn have no KDocs
4. No See also sections in take.kt and drop.kt
Neither drop.kt, take.kt, nor the shared templates contain @see or See also section.
Related operations should link to each other. For example, drop can point to take and the other way around, including their Last/Cols/While variants.
Scope
core/.../documentation/CommonTakeAndDropDocs.kt
core/.../documentation/CommonTakeAndDropWhileDocs.kt
core/.../api/drop.kt
core/.../api/take.kt
Acceptance criteria
@return is correct for all drop* functions while staying correct for take*.
*While KDocs state that dropping/taking stops at the first non-matching column, for both
take and drop.
drop(Last) and take(Last) on DataColumn have KDocs.
- Every function in the
take/drop family has a See also section linking to its counterparts.
CommonTakeAndDropDocsandCommonTakeAndDropWhileDocshold the common docs fordropandtake.1.
@returnis inverted for thedrop*functionsThe generated
@returnis correct fortake, but not fordrop.Following the templates, the KDocs for the operations from
drop.ktsay:Returns: A `ColumnSet` containing the first/last [`n`] columns.But for the
drop*operations it is the other way around: they return everything except those columns.Suggestion: add a
RETURNkey to both templates, set separately fromtake.ktanddrop.kt, or a smaller variable for thecontaining/withoutpart (by @Jolanrensen).2.
*Whiledocs don't say that the run stops at the first non-matching columnFor
dropWhile/dropColsWhile/dropLastWhile/dropLastColsWhile, the KDocs say:"This function drops the first/last columns from
thisadhering to the given predicate collectingthe result into a
ColumnSet."It might not be obvious to the reader that dropping stops with the first element that does not adhere to the predicate (and it is not like "take/drop the first/last n columns).
Suggestion: the meaning would be clearer if the KDocs mentioned something like:
This function keeps dropping the first/last columns from [this] and stops once the given predicate does not hold...(by @Jolanrensen).The same goes for
takeWhile/takeColsWhile/takeLastWhile/takeLastColsWhile3.
drop(Last)andtake(Last)onDataColumnhave no KDocs4. No
See alsosections intake.ktanddrop.ktNeither
drop.kt,take.kt, nor the shared templates contain@seeorSee alsosection.Related operations should link to each other. For example,
dropcan point totakeand the other way around, including theirLast/Cols/Whilevariants.Scope
core/.../documentation/CommonTakeAndDropDocs.ktcore/.../documentation/CommonTakeAndDropWhileDocs.ktcore/.../api/drop.ktcore/.../api/take.ktAcceptance criteria
@returnis correct for alldrop*functions while staying correct fortake*.*WhileKDocs state that dropping/taking stops at the first non-matching column, for bothtakeanddrop.drop(Last)andtake(Last)on DataColumn have KDocs.take/dropfamily has aSee alsosection linking to its counterparts.