apex-dev-tools / apex-dev-tools/apex-ls
Hover: add a tolerant ApexDoc reader and markdown renderer
- 主要语言
- Scala
- 星标
- 12
- 派生
- 3
- 平均合并
- 13 小时 43 分钟
- 30 天内合并 PR
- 19
描述
## Problem
Real-world ApexDoc is highly non-conforming: many comments use decorative delimiters, omit an untagged description, or use community/unknown tags. A strict parser would render empty or misleading hover content, while raw text is noisy and may be unbounded.
## Scope
- Build a tolerant, best-effort ApexDoc reader and markdown renderer.
- Strip `/**`, `*/`/`**/`, leading asterisk runs and banner-only lines while tolerating undecorated lines.
- Parse a main description and block tags; treat `@description` as main-description content.
- Alias `@exception` → `@throws`, `@returns` → `@return`, and `@params` → `@param`; accept dashed parameter descriptions.
- Pass unknown tags through visibly rather than dropping them.
- Initially render `{@code}` as code and `{@link}`/`{@literal}` as text; deliberately ignore generator-only hiding semantics.
- Cap long descriptions while retaining recognized tag sections, and combine the result with the fenced signature from A.
## Non-scope
- Resolving `class#member` links.
- Compiler validation or diagnostics for malformed docs.
- Capturing spans or expanding hover targets.
- Content-sniffing licence/copyright detection.
## Acceptance criteria
- Spec-style and measured community-style examples render useful markdown, including tag-only comments using `@description`.
- Decorative banners, alternate terminators, single-line comments and lines without leading `*` are handled.
- Unknown/misspelled tags remain visible, and malformed content falls back to stripped text or signature-only hover without logging issues.
- Output length is deterministically capped and markdown-significant content cannot corrupt the signature fence/structure.
- Focused tests cover aliases, unknown tags, inline tags, malformed input and the cap.
## Dependencies
Depends on **B**: #565, and uses A's explicit markdown payload: #564.
## Repository/API compatibility
Keep the reader independent of parser implementation and usable for full and summary-backed spans. Rendering is deliberately tolerant rather than a Salesforce compiler validator. Review the useful ideas in the closed experimental PR #391, but do not treat that PR as an active implementation.
## Context
Split **F** from #325. See the detailed [Proposed scope split and investigation](https://github.com/apex-dev-tools/apex-ls/issues/325#issuecomment-5347298995).
贡献指南
这个仓库没有索引到贡献指南
调研方向
Start by reading dependency issues #565 and #564, then review the useful ideas in closed experimental PR #391 and the scope split in #325. Define completion against the listed acceptance criteria: tolerant parsing and rendering, visible unknown tags, safe deterministic capping, signature preservation, and focused tests for aliases, inline tags, malformed input, and the cap.
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- markdown, scala
- 领域
- documentation, tooling
- Issue 类型
- 功能
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 活跃度
- 活跃
- 描述清晰度
- 基本清楚
- 新手友好度
- 52/100