apex-dev-tools / apex-dev-tools/apex-ls

Hover: add a tolerant ApexDoc reader and markdown renderer

未关闭
#568 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
enhancement
主要语言
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

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。