adobe / adobe/hyde

Out of line documentation and examples?

Open
#88 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
340
Forks
45
PR merge metrics
No merged PRs in 30d

Description

To quote `README.md`:

> Out-of-line: Many tools rely on documentation placed inline within source as long-form comments. While these seem appealing at first blush, they suffer from two big drawbacks. First, there is nothing keeping the comments from falling out of sync from the elements they document. Secondly (and ironically), experienced users of these libraries eventually find inline documentation to be more of a distraction than a help, cluttering code with comments they no longer read.

If I am understanding this correctly, it is possible to have documentation source in a file separate from the code? This feature does not seem to documented in any way, and I also couldn't find any examples.

Contributor guide

Open the contributing guide

Research direction

Start with the out-of-line documentation section quoted from README.md and inspect the project for any documented or example usage of separate source files. Confirm whether this capability exists, then document the supported workflow and add a minimal example if the repository already provides a suitable location.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.