Thank you very much for all the responses; especially Duncan's guidance.
I will add some further ideas on workflows below.
There were quite a few views on GitHub; but there is not much to see, as
there is absolutely no documentation. I have added in the meantime a
basic example:
https://github.com/discoleo/BioShapes/blob/main/Examples.Bioshapes.png
The actual code can do a lot more.
############
Some ideas on workflows:
1. Most code is written as C/C++; the R code is a thin wrapper around
the C/C++ functions
It is practical to embed the documentation with the R code - as there is
no complex code anyway. The same may apply for small packages.
2. Complex R code
The comments may clutter the code. It is also difficult to maintain this
documentation, as the comments are less easily readable. Separating the
documentation from the code is a good idea.
Unfortunately, this is not so obvious when you start working on your
first package.
Many thanks,
Leonard
On 9/4/2023 5:47 AM, Jeff Newmiller wrote:
Leonard... the reason roxygen exists is to allow markup in source files to be
used to automatically generate the numerous files required by standard R
packages as documented in Writing R Extensions.
If your goal is to not use source files this way then the solution is to not
use roxygen at all. Just create those files yourself by directly editing them
from scratch.
On September 3, 2023 7:06:09 PM PDT, Leonard Mada via R-help
<r-help@r-project.org> wrote:
Thank you Bert.
Clarification:
Indeed, I am using an add-on package: it is customary for that package -
that is what I have seen - to have the entire documentation included as
comments in the R src files. (But maybe I am wrong.)
I will try to find some time over the next few days to explore in more
detail the R documentation. Although, I do not know how this will
interact with the add-on package.
Sincerely,
Leonard
On 9/4/2023 4:58 AM, Bert Gunter wrote:
1. R-package-devel is where queries about package protocols should go.
2. But...
"Is there a succinct, but sufficiently informative description of
documentation tools?"
"Writing R Extensions" (shipped with R) is *the* reference for R
documentation. Whether it's sufficiently "succinct" for you, I cannot
say.
"I find that including the documentation in the source files is very
distracting."
?? R documentation (.Rd) files are separate from source (.R) files.
Inline documentation in source files is an "add-on" capability
provided by optional packages if one prefers to do this. Such packages
parse the source files to extract the documentation into the .Rd
files/ So not sure what you mean here. Apologies if I have misunderstood.
" I would prefer to have only basic comments in the source
files and an expanded documentation in a separate location."
If I understand you correctly, this is exactly what the R package
process specifies. Again, see the "Writing R Extensions" manual for
details.
Also, if you wish to have your package on CRAN, it requires that the
package documents all functions in the package as specified by the
"Writing ..." manual.
Again, further questions and elaboration should go to the
R-package-devel list, although I think the manual is really the
authoritative resource to follow.
Cheers,
Bert
On Sun, Sep 3, 2023 at 5:06 PM Leonard Mada via R-help
<r-help@r-project.org> wrote:
Dear R-List Members,
I am looking for collaborators to further develop the BioShapes
almost-package. I added a brief description below.
A.) BioShapes (Almost-) Package
The aim of the BioShapes quasi-package is to facilitate the
generation
of graphical objects resembling biological and chemical entities,
enabling the construction of diagrams based on these objects. It
currently includes functions to generate diagrams depicting viral
particles, liposomes, double helix / DNA strands, various cell types
(like neurons, brush-border cells and duct cells), Ig-domains, as
well
as more basic shapes.
It should offer researchers in the field of biological and chemical
sciences a tool to easily generate diagrams depicting the studied
biological processes.
The package lacks a proper documentation and is not yet released on
CRAN. However, it is available on GitHub:
https://github.com/discoleo/BioShapes
Although there are 27 unique cloners on GitHub, I am still looking
for
contributors and collaborators. I would appreciate any
collaborations to
develop it further. I can be contacted both by email and on GitHub.
B.) Documentation Tools
Is there a succinct, but sufficiently informative description of
documentation tools?
I find that including the documentation in the source files is very
distracting. I would prefer to have only basic comments in the source
files and an expanded documentation in a separate location.
This question may be more appropriate for the R-package-devel list. I
can move the 2nd question to that list.
###
As the biological sciences are very vast, I would be very happy for
collaborators on the development of this package. Examples with
existing
shapes are available in (but are unfortunately not documented):
Man/examples/Examples.Man.R
R/Examples.R
R/Examples.Cells.R
tests/experimental/*
Many thanks,
Leonard
______________________________________________
R-help@r-project.org mailing list -- To UNSUBSCRIBE and more, see
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
<http://www.R-project.org/posting-guide.html>
and provide commented, minimal, self-contained, reproducible code.
[[alternative HTML version deleted]]
______________________________________________
R-help@r-project.org mailing list -- To UNSUBSCRIBE and more, see
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
______________________________________________
R-help@r-project.org mailing list -- To UNSUBSCRIBE and more, see
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
