patreon / nion Goto Github PK

There's some things in the /docs folder that haven't been touched in 10 months, are aren't linked to from the Readme.

1. Are those docs still accurate?
2. Are they specific to internal use?
3. Should they be linked to in the Readme, or removed?

what do they do? what are they for? right now there's a bunch of stuff that can be tossed in willy-nilly... what about append?

This issue was created automatically. See associated PR for details.

It's a totally valid and well-tested option, but it's missing from the type definition file.

It's causing this issue:

This relates to #82. Documentation on nion is difficult to navigate, and often results in users old and new being forced to read the source code of nion. Here is a plan to solve this by streamlining the docs.

At the center of this refresh is a single Markdown file that is designated the Walkthrough. The Walkthrough is what the README file should link to at the end of the "In a nutshell" section. It should:

• better reflect the journey of someone new to nion
• serve as a much more cohesive index to various topic for existing users of nion

In essence, it's a fancier version of the index to the ./docs directory.

Note: all links to the repo are pinned to the SHA-1 95ffcdc, which is master at the time of writing.

Overview

1. Rename Getting Started to "Setup and Configuration". This doc is not a required read for someone working on a codebase that already uses nion.

2. Create the Usage file. It will illustrate the three forms of nion: hook, HOC, and decorator. See #110 for work in progress.

3. Create the Walkthough file. Its tentative name is index.md and its tentative H1 heading is "Getting Started on nion".

   • H2: "New to nion?"
     • Check out Usage, Declarations, Examples, Core (shallow)
   • H2: "Hello, old-timer"
     • Check out Glossary, Core (deep), and other in-depth stuff

4. Merge nion api into Declarations.

   • Clearly illustrate which declaration options are common, unique to hooks, or unique to HOC.
   • Verify each option's Required status and fix where necessary.
   • Reorganize the three declaration forms — function-returning-object, object, string — as a cascade of syntactic sugar.
   • Sync with #107 to ensure that the description of various options is consistent.
   • Docgen stretch (see section below for details)

5. Create a hooks version of Examples.

   • Verify that all existing examples are valid
   • Rewrite existing examples to use the plain HOC syntax instead of decorators
   • Produce hooks-equivalent examples

6. Merge How nion works into nion core and rename to "Internals". Both pages document nion internals; they differ by how deep of a dive they take the reader. Divide the page by section to delineate shallow snorkeling from deep dive.

7. Ensure Glossary is up-to-date

   • Sync with #107 to ensure that the type names therein match the terms in Glossary
   • Docgen stretch (see section below for details)

Docgen stretch

When #107 merges, we will effectively have a single source of authority for API usage. This paves the way for using an automated tool to generate documentation from code, e.g. extracting JSDoc blocks into neat pages. This would let us semi-automate the Glossary and Declaration docs so that they match the type definitions exactly.

Ordering

The order of the steps outlined in Overview is merely a suggestion. Furthermore, the Walkthrough itself should be continuously updated as various pages are merged, rewritten, and reorganized.

Feedback

None of this is set in stone; comments are always welcome.

per @mikejonas, it seems as if the refToDelete meta key causes the entity to be deleted to just be subbed out with undefined rather than being filtered out of lists... this is incorrect behavior