Documentation (Developer's Perspective)

Main Functional Blocks

Although things are not totally clear-cut, it seems useful to divide the package in 3 main functional blocks:

Package Loading and Options Management Block
Content Production Block
Content Rendering Block

Finally, there are some utility functions which do not clearly belong in any of the three main blocks, and which do not themselves form a cohesive block; for now, let's just take note of them:

• the what.is() function
• the label() function
• the tb() function

1. First Block: Package Loading and Options Management

1.1 The Initialization file: zzz.R

What is does:

• initializes .st_env an environment (used as a list) which will store
  • package options
  • the platform (Windows / Mac / *nix)
  • customized "translations", i.e. specific terms defined with define_keywords()
  • information on the current iteration when stby() or by() are used
• checks for X11 capabilities as well as pander version and displays appropriate messages

1.2 The st_options() Function

1.3 i18n mechanics

• define_keywords()
• use_custom_lang()
• a few helper functions.

2. Second Block: Content Production

The second block is comprised of the 4 core functions, the by-group processing mechanics (stby() being only a small part of it), as well as metadata extraction (the internal parse_args() function, which is not really aptly named).

Here are a few examples, followed by a rough flowchart.

dfs_iris1  <- dfSummary(iris)
dfs_iris2  <- stby(iris, iris$Species, dfSummary)
descr_iris <- iris %>% group_by(Species) %>% descr()

2.1 Content Production Flowchart

If you're thinking "hmmm that looks kinda messy", well, I can't disagree. If I were to redo everything from scratch, surely things would look different. And for now nothing is off the table. If a complete redesign is what it takes and there's enough brain and finger power available, maybe wiping the slate clean is the proper way to go. Advantages of S4 over S3 should also be discussed.

For more details, see this image. I know, it's not the prettiest. I did this rather quickly.

2.2 By-Group Processing

2.3 The Four Core Functions

2.4 Metadata Extraction

2.5 Helper Functions

3. Third Block: Content Rendering (Printing Objects)

The third block is all that pertains to rendering, i.e. the print methods & the view() function as well as their internal helper functions.