AlexsLemonade / AlexsLemonade/rOpenScPCA

Ensure docs follow the standard format

Open
#27 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
0
Forks
2
PR merge metrics
No merged PRs in 30d

Description

> > Counterpoint: It turns out this is a great demonstration of "people may miss docs if they have to scroll past arguments".
>
> I want to note that I'm conflicted here! I very much take the point that the docs are there, I just missed them, but how _meaningful_ is it that I missed them is the question I'm not sure of...

I think my general thought is that we should probably follow the standard format more closely. If the expected documentation standard is that descriptions should be a short paragraph, we should do that, and put the rest in the details section. I don't think that the usage of this package deviates in any significant way from any other package that would justify doing things much differently.

That may mean some reformatting, and I am not wholly opposed to adding `@description` and `@details`; I just don't think we need to do it everywhere as you have done here. (And I would keep them on their own lines for aesthetics.)

I was also partly confused by your initial description of the problem, where you talked about line breaks, but what you meant was paragraph breaks (blank lines).

_Originally posted by @jashapiro in https://github.com/AlexsLemonade/rOpenScPCA/issues/26#issuecomment-2557571507_

----

This issue was opened in lieu of #26 to update the docs, where needed, to ensure they follow a standard format as described.

Contributor guide

No contributing guide indexed for this repository

Research direction

No files or tests are named. Start by identifying the package documentation covered by this issue and compare it with the standard format described in the discussion, including short descriptions and separate details where needed. Done means the relevant documentation has been consistently reformatted without unnecessary changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
r
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.