What's about roxygen2 type of documentation for DescTools?

[GegznaV]

@AndriSignorell, did you consider going from Rd documentation to markdown flavored roxygen2 documentation (which automatically generates Rd files)? It could be written in markdown so it is easier to read for developers (and spot typos and other discrepancies), the documentation is above the function so it is easier to understand what function does when you read .R files, some fields such as Usage are auto-generated so it is easier to maintain the documentation. There are specialized packages (e.g., Rd2roxygen and roxygen2md), that alleviate transitioning from the manually written Rd files to roxygen2 documentation. And we can use GitHub Actions to build documentation every time the package is uploaded to GitHub (so it is not required to do it locally).

roxygen2 can help to maintain the NAMESPACE file too.

[GegznaV]

Any ideas?

[AndriSignorell]

Well, ehhh... hmm, not sure about that... give me some more time to consider. ;-)

[GegznaV]

There are automatic tools that may help. But the package is big, so I'd suggest a gradual transition.

[AndriSignorell]

I aggree that it would be a good idea to transfer the documentation to roxygen2. So we could start with Desc which has insufficient documentation anyway. The documentation has grown historically and is undoubtedly chaotic in character. However it would be better from my point of view to separate the helpfiles for

• {Desc.numeric, Desc.integer},
• {Desc.factor, Desc.ordered, Desc.labelled},
• Desc.logical,
• {Desc.table, Desc.matrix},
• {Desc.date, Desc.ts}
• {Desc.data.frame, Desc.list}
• Desc.formula
• some generic information about {Desc, Desc.default}

as the calculations and the plots are extremely different. As a first step, I would split the Desc routines into specific files of their own in order to gain a better overview.

[GegznaV]

To create separate documentation files, @name and @rdname tags can be used. This post describes how to reuse documentation from similar functions. Yet, in the long run, I would like to have the interfaces of the same name functions (different methods) to be more unified than they are now as this gives more consistency.

[AndriSignorell]

Could you be more specific about the required interface changes? Maybe this would be the moment to revise the functions and their interfaces (including the docu) ...

[GegznaV]

E.g., in generic function main, plotit go as non positional arguments, and in the methods – as positional:

In the next example, the same color shows the same argument and the numbers show their position:

Usually, a good practice is to have all common arguments as positional ones before ..., and method-specific ones should go after .... Of course, it is not necessary to follow this recommendation 100%, but I constantly got confused about different data types and had to look up the documentation (or method definitions).

An exception is the formula method which is always different.

So maybe it is a good time to consider which arguments could always be in the same positions at the beginning.

Similar consistency principles could be applied to print and plot methods. For plot, the first 4 arguments could be x, xlab, ylab, and main.

[AndriSignorell]

Good point, I will put things together ...

[AndriSignorell]

Here we go:

GetArgs <- function(FUN) {
  a <- formals(getAnywhere(FUN)$objs[[1]])
  arg.labels <- names(a)
  arg.values <- as.character(a)
  char <- sapply(a, is.character)
  arg.values[char] <- paste("\"", arg.values[char], "\"", sep="")
  c(fname=FUN, args=paste(StrTrim(gsub("= $", "", paste(arg.labels, arg.values, sep=" = "))), collapse=", "))
}

fcts <- grep("plot.Desc", unclass(lsf.str(envir = asNamespace("DescTools"), all.names = T)), v=T)
fargs <- t(unname(sapply(fcts, GetArgs)))

actually not really worked out...

[GegznaV]

It is brilliant! Task automation helps to spot things more easily.

[GegznaV]

A few more questions/remarks:

1. For consistency with other methods, could we have col instead of col1?
2. And for me, it would be more intuitive to have add_n instead of add_ni. It is not a crucial thing, but just an idea to consider.

[AndriSignorell]

Well, I think the situation needs an even more fundamental revision...