Skip to content

[Feature/Addition] Update documentation to indicate what table columns you get after running various methods #1475

@anzelpwj

Description

@anzelpwj

Detailed Description

Something that's been kind of annoying for me is that I have to run Parsons code and then inspect the generated PETL table to know what sort of data I'm expecting to get. If it's pretty clear ahead of time what data we're getting, why don't we make our docstrings more informative about what we get?

For example, for parsons/ngpvan/email.py:get_email_stats we just have the docstring:

        `Returns:`
            Parsons Table
                See :ref:`parsons-table` for output options.

What if we instead did something like:

        `Returns:`
            Parsons Table
                See :ref:`parsons-table` for output options. Returned columns are: name, createdBy,
                dateCreated, dateModified, dateScheduled, foreignMessageId, recipientCount,
                bounceCount, contributionCount, contributionTotal, formSubmissionCount,
                linksClickedCount, machineOpenCount, openCount, unsubscribeCount, subject

Context

This is mostly a quality of life improvement. If I can browse the docs as I'm looking for methods, this can help me be more clear if a method is returning the data I expect it to.

Possible Implementation

Suggested form is above, but if there is a preferred way to do it I'm happy to follow whatever convention we have.

Priority

Nice to have, not make-or-break. Work on this can probably be done piecemeal.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementImpact - something should be added to or changed about Parsons that isn't causing a current breakage

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions