Out of line documentation and examples?

[jaskij]

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.

[fosterbrereton]

it is possible to have documentation source in a file separate from the code?

Yes- this is one of the main features of Hyde. The tool is a C++ compiler that produces documentation (instead of an executable). This documentation takes the form of dozens of Markdown-based files (with YAML front-matter). The files live externally to the source code, but are kept in sync with the source code by successive runs of Hyde. Developers can add more documentation to the files Hyde maintains, and the tool will preserve that documentation as well.

[fosterbrereton]

As far as examples, here is a sample website built with the documentation Hyde produces (using this build script) from the example files in the Hyde repo.

[jaskij]

@fosterbrereton all those files have the documentation inline, in the code, though.

Perhaps we have different understandings what "separate from the code" means here?

[sean-parent]

hyde 2.0 supports a hybrid model where docs can be pulled from comments in the code as well as added to in the generated .md files (which hyde can update). For example, in this file:

https://raw.githubusercontent.com/stlab/libraries/main/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_append.md

The inline: description: is pulled from the source. But the description: "Iis a model offorward_node_iterator.\n" only exists in the .md file. The resulting docs are here:

https://stlab.cc/includes/stlab/algorithm/reverse.hpp/f_reverse_append.html

You can also add whatever long-form description you want to the markdown file, and it will be preserved/updated by Hyde. Initially in stlab we had all docs only in Hyde (none in the sources) but we are moving towards keeping the brief descriptions in the sources. We just went through a major restructuring of both code and docs and now most of the docs are just the Hyde generated ones while I'm putting the pieces back together.

The stlab site is using the adobe/hyde-theme directly.

On Thu, Jul 11, 2024 at 3:17 PM jaskij @.***> wrote:

@fosterbrereton https://github.com/fosterbrereton all those files have the documentation inline, in the code, though.

Perhaps we have different understandings what "separate from the code" means here?

— Reply to this email directly, view it on GitHub https://github.com/adobe/hyde/issues/88#issuecomment-2224042446, or unsubscribe https://github.com/notifications/unsubscribe-auth/AARMSLE4PTUL5FDMXSU6KKLZL4AANAVCNFSM6AAAAABKW4DTSGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMRUGA2DENBUGY . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[jaskij]

Thank you @sean-parent , this is exactly the kind of example I was looking for. Knowing what to look for, I was also able to find docs/libraries in this repository, which seems to go together with the examples in test_files/.

The one question I still have is how do those paths and file names work together. Probably something I'd be able to figure out once I get around to actually testing hyde.

Leaving this issue open because does not seem to be documented in hyde itself.