Bug: No descriptions provided in documentation

[vitonsky]

Lexical version: 0.19.0

Steps To Reproduce

1. Go to documentation site. For example let's open URL https://lexical.dev/docs/react/ or https://lexical.dev/docs/api/modules/lexical
2. Try to understand lexical API

Link to code example: https://lexical.dev/docs/api/modules/lexical

The current behavior

No descriptions provided for most of https://lexical.dev/docs/api/modules/lexical API:

No any description for API of https://lexical.dev/docs/react/

I've found code usage like import { useLexicalNodeSelection } from '@lexical/react/useLexicalNodeSelection'; so i tried to found what is useLexicalNodeSelection but nothing about it in docs.

Currently it seems like project created for the inner usage in Facebook, but not for the external developers and projects.

Since i just met with this project, i don't know how it work and i can't. All i can is to read core concepts and then read code in repository.

The expected behavior

Site contains clear descriptions for every single public entity. Description explain the purpose and value or use cases of entities, like it do an MDN or any other good docs site like react docs.

Impact of fix

Add descriptions. It would benefit all developers who need a reach editor for their projects.

Currently docs have so few information that i feel this project is dead. I've just checked and i see last commit been 3 hour ago, so it confuse me and make me think that Lexical developing not for the world.

---

P.S. Could you please elaborate current status of Lexical.

[etrepum]

You're right that there is a lot of missing documentation, and that to make a lot of progress with the library you're probably going to need to read its source, or at least the source of the examples and/or playground. This is not uncommon in open source projects, especially in a <1.0 state. The project is clearly under active development and not dead, and many of its users and contributors are not at Meta.

I think this issue is a bit too vague to do anything about, nobody is going to take the time to add docstrings to every single export in the code base in one sweep, but if you want to break this up into more specific requests about functions or types where the usage is unclear, it may be useful.

[vitonsky]

if you want to break this up into more specific requests about functions or types where the usage is unclear, it may be useful.

I would know about core functional. We could start from functions on page https://lexical.dev/docs/api/modules/lexical and explain their purpose with some explanations.

I can assume what about functions with name like $isTextNode, that is pretty obvious, but i no have idea what to do functions like $parseSerializedNode.

Initially i've go to docs to understand how i can get node by its key. But:

• I did not found any information in docs that confirm my assumption that a key is unique
• I did not found API to get node by its key. Currently i do it like that editor.getEditorState()._nodeMap.get(nodeKey) and i'm not sure that's correct way

It would be nice to start document core API i've mention. What you think about it?

---

Also i have question about project development plan. Do you have any?

I'm interesting when users may expect version 1.0, to better understand should we start use this library that looks powerful.

Also it is interesting who can contribute to this project. Is it really opensource? I've found next message in PRs:

so it looks that not everyone can contribute to this project.

[etrepum]

Rather than starting by reading all of the function names and just guessing, I would recommend that you start by reading through the guides and the examples. There are a lot of exported functions and the API docs will likely not be helpful until you already know what you're doing, and some of them are primarily implementation details that are used in very advanced use cases. For example $parseSerializedNode is mostly only exported so that it can be used by $generateNodesFromSerializedNodes (which does have documentation).

The function you're looking for is $getNodeByKey to look up a node by its key from the active editor state. If there's an underscore on a property it is not part of the public API.

Yes that's right, contributions are not accepted until the CLA is signed. Anyone can sign the CLA, but if you refuse to sign it you can not contribute to this repository.

No, there is no public roadmap for what a 1.0 release will look like or when it might happen. The project is still under active development and the kind of stability guarantees that you would get from a 1.0 release are not currently feasible.

[vitonsky]

Rather than starting by reading all of the function names and just guessing, I would recommend that you start by reading through the guides and the examples.

That is not how we develop software in our team. In case some library require to explore source code in its repository - this library is not ready for wide use. There are great blog post about it

My expectation is library will provide core concepts explanation, and API documentation. If this conditions have been met, i no need to guess what functions do - i will make plan with features i need in my application, then i will plan how to implement it in terms of core conceptions and primitives, then i will write code and will looking for an API/utils that do something i need by descriptions with this terms.

The function you're looking for is $getNodeByKey to look up a node by its key from the active editor state. If there's an underscore on a property it is not part of the public API.

Thank you.

Yes that's right, contributions are not accepted until the CLA is signed. Anyone can sign the CLA, but if you refuse to sign it you can not contribute to this repository.

How to contribute to this project? Can i just sign CLA online and then make pull requests i want or you have some process about it and some features plan we have to work on?

No, there is no public roadmap for what a 1.0 release will look like or when it might happen. The project is still under active development and the kind of stability guarantees that you would get from a 1.0 release are not currently feasible.

What do it means for my project that need a powerful rich text editor?

Should i consider alternatives like https://www.slatejs.org because no stable API and documentation will not appears until version 1.0 that may never be released or will be released since 10 years?

Or this project have some more precise plans and time ranges?

[etrepum]

This is an open source project, provided at no cost developed in large part by volunteer effort. You get what you get, whether that meets your expectations or not. If you want improvements in some specific direction, contributing is the primary way to make that happen. If it's not suitable for your purposes in its current state, and you're not willing to contribute to get it there, then don't use it.

Yes, anyone can submit a PR and sign the CLA (even in that order). There are no other requirements. Typically PRs will be accepted if they're generally useful, correct, and are not a maintenance burden. People submit PRs relevant to their own interests, to support their own projects. There is not some product manager out there distributing tasks. If you're looking for arbitrary tasks to do you can peruse the issues, but in many cases they will require significant expertise to investigate and solve.

[vitonsky]

@etrepum who make decisions on project and how you rule conflicts?
If you have many contributors with different vision how to implement some feature - what you will do?

Who's the architect? Do you have the one who has invent the core concepts of a project, and who know how to develop project consistently from a design perspective.

[etrepum]

There's a small team of core contributors that review and merge PRs and chat regularly. Conflicts are resolved by discussion. Since it's a Meta project, and they are the largest consumer of the project, whoever is responsible for the project on their team at the time ultimately has the final say if it's not otherwise clear.

The architecture was developed over several years of effort by multiple people and continues to be refined. The people who did the most work on those early decisions are not so active on the project at the moment, so I wouldn't say that there's one architect with a singular vision at this point.

[vitonsky]

@etrepum how developers communicate on this project?

I appreciate you answer my questions here, it even related to issue topic about figuring out how project work and develops, but issues may be not ideal place for questions, so i want to clarify it.

For example, i have question about @lexical/markdown module. Current design uses regex to detect features by match text and then transform it to lexical nodes. The problem I see here is we have to re-implement parsing markdown, although there are a lot of markdown parsers like https://github.com/syntax-tree/unist and https://github.com/syntax-tree/mdast

My question is why current design has been chosen? Do we have some research work around possibility to integrate MD AST parsers into plugin to handle markdown?

If we would use such parsers, we could use their plugins to implement any markdown features, and we would just map MD AST nodes to lexical nodes.

Isn't this decision motivated by "not invented here" vision?

[etrepum]

Discord. https://lexical.dev/community

To the best of my knowledge the markdown implementation is bespoke for bundle size reasons for the original use cases it was developed for. There's no reason you couldn't develop something full featured on a better parser, but nobody has done that yet and packaged it up for use. It's very modular, the markdown package is not tied to the core or required by other packages.