Skip to content

Fix take/drop KDocs #2018

Description

@Allex-Nik

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    KDocsImprovements or additions to KDocs

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions