"fix" roxygen markup for internal function

[MichaelChirico]

Came across this by accident in an over-wide Ctrl+F, so offering the fix. Not really a bug since the function is interal.

[gavinsimpson]

I think the : was intentional, but perhaps missing an a after the colon so it reads : a number... or even ; a number... (which is how I usually write these argument things).

[jarioksa]

I wrote this line in 2014 – I don't remember what was my intention and I don't want to speculate. Please note that vegan documentation was never maintained in roxygen (and will never be maintained in roxygen) and these roxygen pieces were never processed. No reason not to apply the fix, though.

I think the roxygen is a flawed idea – similarly as other systems as doxygen etc. – and supports bad documentation. It is possible to write good documentation with roxygen, but mixing the documentation with code development easily leads to excessively technical documentation for other programmers instead of helping the users. This has been discussed elsewhere like recently on doxygen documentation in PostgreSQL in https://lwn.net/Articles/934674/. Roxygen offers some useful features, especially maintaining documentation of API (section Usage), but section Details and most others should be written for users and separately and not for developers during coding. From the git point of view, I would also like to keep separate the changes in code (R files) and documentation (Rd files) instead of changing Rd files by editing R files. In particular, changes in both in one commit is very effective in hiding the crucial changes in code.

[jarioksa]

In addition to maintaining API, another very valuable feature in roxygen is maintaining NAMESPACE or maintaining imports and exports. In the vegan context, I don't believe that these two valuable features outweigh the pain of transforming all manual to roxygen. If we only could have a version of roxygen that only takes care of these two pieces (which also are best edited during development) but allows us have a separate documentation for the users.

[MichaelChirico]

FWIW I think you could accomplish that by only running roxygenize(rockets = "namespace"). that way you could keep @export tags in the sources but not user-facing documentation.

[jarioksa]

@MichaelChirico thanks for the hint. Just last year I updated vegan NAMESPACE to use specific importFrom in all cases. An advantage of roxygen would be that it can remove the imports that become unused and stale in development. Adding importFroms to all vegan functions is so tedious and boring job that I'll probably find some other things to do that are more fun.

Still having the API update (param) in docs would be nice.