Show HN: Hyde – An out-of-line C++ library documentation tool | Hacker News Reader

Show HN: Hyde – An out-of-line C++ library documentation tool

github.com

36 pointsMontagFTB30 comments

> 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.

Do they? In 20+ years of professional software development I have not once heard this. I heard lots of criticism about bad documentation of the style

  // Increment i by 1
  i++;

but never ever fundamental criticism of inline comments except from the literal programming community (I think they have a point there, but their baseline is considerably higher).

Edit: Using clang is a very good choice, imho. If I was coding in c++, I'd probably use the tool just for that alone.

I have heard the inline comment complaint first hand, especially as it relates to documentation of library headers. The biggest issues come from long-form commentary between every API that add more noise than signal to a header file. To be sure, inline commentary of any kind is better than none at all! However, an inflection point exists where the source file is a poor medium for exhaustive documentation meant for human consumption. As an open source library maintainer, too, I have found this style of documentation problematic to maintain.

Brief comments that should be digested nearly every time an API is referenced (e.g., because there is a funky precondition or some other gotcha a user should be aware of) are certainly useful, and comments within the implementations of routines are good to have. In general, code should speak for itself, and any associated comments should fill in gaps where the code's intent is not obvious. Such code commentary is not the problem hyde is looking to solve.

Don't load header files with documentation comments. Put them in the implementation.

I don't see where the trouble is in properly documenting your code within the code. That isn't any where near as intrusive as literate programming. On an active code base nobody is going to keep external docs up to date without a taskmaster to force the issue.

Open source code bases are often a poor example of good coding practices. 1000's of lines can go by with nary a comment. Everybody's so leet they don't need them? That's great if you are the principal author and know (or knew) what everything did at one time. Not so great in a commercial setting with a fluid developer base where the noobs need to know what's going on without reading every piece of code.

> Don't load header files with documentation comments. Put them in the implementation.

no, that's terrible. How do you do when you don't want to install the source of every lib you use ?

You read the generated docs or get the source.

Not sure where we disagree: Bad documentation is bad. Yes. But what is specific about inline comments per se?

I think we agree far more than otherwise. Where we might disagree is with my claim that good, long-form documentation of sources/headers/APIs is better done out-of-line.

Fair enough, I never said anything about "long form documentation" ;)

Just not enough info in that readme. A simple example would help a lot - showing input file and output file. It can be the most trivial case (10 line files).

I'm also concerned about a tool which must get updated in time with compilers. That means that there will always be some period where the two are out of sync - and that is unacceptable for any project I've ever worked on.

The tool produces multiple output files for a single input. For example:

input: https://raw.githubusercontent.com/stlab/libraries/develop/st...

output: https://github.com/stlab/stlab.github.io/tree/master/librari...

As for updating the tool, it's currently building against the top of the Clang tree. In my experience, there are other elements of one's tooling chain that take a longer time to catch up. (For example, Xcode is only periodically released, and even then is using a version of Clang that is somewhat behind. Something similar could be said for MSVC.) Nothing about the tool is closed-source, so it should be easy for anyone to clone the repository and build it against an updated version of the compiler.

Your output link just shows a load of JSON to me...

The output files are Markdown-formatted with YAML front-matter. The intent is for these files to be fed into a static site generator, like Jekyll. There are tags that require developers fill in the details, which the tool marks as missing. The tool handles all the structuring of the documentation, leaving the meaty details up to the library producers. Then, when combined with your site's static site layout, the output documentation looks however you'd like it to.

I don't see any markdown though. And you should show the html output as an example. (if you want users anyway)

A sample of the kind of documentation it can produce is here: http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...

I agree with the folks here who pointed out this thing needs a succinct example to communicate what it does.

Came here because I thought maybe someone had finally implemented an idea I had for a two-pane coding IDE where "out-of-band" documentation for the function you're working on is shown/edited on the right. (BTW does that exist?)

A sample of the documentation can be found here: http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...

The installation steps seem to require Homebrew. Is this macOS-only?

The tool was built on the Mac, though its dependencies are not Mac-specific, and we use CMake to generate necessary build files. Any PRs to get it building on other platforms would be most welcome.

Question, any live examples?

Live? Even offline examples would be great. The description is painfully laconic and it's really hard to guess what exactly is generated. Which is a shame, because the project looks like a rather nice solution to really common problem

If the repository README isn't clear, please let me know what more you would like to see there. From that document:

> hyde does not produce pretty-printed output. Rather, it produces well structured Markdown files that contain YAML front-matter. These files can then be consumed by other tools (like Jekyll) to customize the structure and layout of the final documentation.

Generally sibling comment by IshKebab lists most of the things that were not clear for me. The biggest point, however, is that I wasn't able to get clear picture of what is considered here to be the "documentation". I get what file format is generated, but I have no idea what will be the content and how it will be inferred from my code.

Well you don't have any examples of the documentation that is produced. Our even of how you actually write the documentation.

To me the readme and examples you've linked read like:

1. You write normal code with no inline documentation, and no links to external documentation.

2. You run it through a tool with produces JSON. And feed that into a static sure generator.

3. Your code is now magically documented. Somehow.

I have no idea where the actual documentation is...

A sample of the kind of documentation it can produce is here: http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...

Ah this looks nice! Would be helpful to know how you go from hyde output to this result and where it gets "notes" from.

Ok this should be the first link in the readme.

> please let me know what more you would like to see there

I would love to see Hyde dogfood Hyde. I think that might be helpful to those coming in to check it out. What does the documentation of Hyde look like put through Hyde and output through vanilla Jekyll?

Clever name, by the way.

We are in the process of updating/migrating the docs at http://stlab.cc over to hyde. GitHub is being slow today, so the site changes aren't live yet. However, you can view the sources (what hyde actually outputs) here: https://github.com/stlab/stlab.github.io/tree/master/librari... . Any file within there was created by the tool (for example: https://raw.githubusercontent.com/stlab/stlab.github.io/mast...)

The above documentation is derived from the following source file: https://github.com/stlab/libraries/blob/develop/stlab/copy_o...

I am genuinely curious what's out-of-line mean here, especially comparing with Doxygen. Doxygen can generate xml output, and these xml output are easy to parse to either generate markdown, or rst, and then feeding to to Jekyll or Sphinx.

They can't keep getting away with it.

Reply on news.ycombinator.com