5 ms·
Show HN: Hyde – An out-of-line C++ library documentation tool
- mempko 8y agoQuestion, any live examples?
- mbel 8y agoLive? 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
- MontagFTB 8y agoIf 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.
- IshKebab 8y agoWell 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...
- MontagFTB 8y agoA sample of the kind of documentation it can produce is here: http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_write3CT3E/ http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...
- mbel 8y agoGenerally 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.
- factotvm 8y ago> 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.
- MontagFTB 8y agoWe are in the process of updating/migrating the docs at http://stlab.cc 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/libraries/stlab2Fcopy_on_write.hpp 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/master/libraries/stlab2Fcopy_on_write.hpp/copy_on_write3CT3E/m_copy_on_write3CT3E.md 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_on_write.hpp https://github.com/stlab/libraries/blob/develop/stlab/copy_o...
- liuliu 8y agoI 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.
- biII_cosby 8y agoThey can't keep getting away with it.
- jlg23 8y ago> 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.
- MontagFTB 8y agoI 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.
- jlg23 8y agoNot sure where we disagree: Bad documentation is bad. Yes. But what is specific about inline comments per se?
- MontagFTB 8y agoI 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.
- MrTonyD 8y agoJust 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.
- MontagFTB 8y agoThe tool produces multiple output files for a single input. For example: input: https://raw.githubusercontent.com/stlab/libraries/develop/stlab/copy_on_write.hpp https://raw.githubusercontent.com/stlab/libraries/develop/st... output: https://github.com/stlab/stlab.github.io/tree/master/libraries/stlab2Fcopy_on_write.hpp 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.
- IshKebab 8y agoYour output link just shows a load of JSON to me...
- MontagFTB 8y agoThe 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.
- saagarjha 8y agoThe installation steps seem to require Homebrew. Is this macOS-only?
- MontagFTB 8y agoThe 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.
- rkagerer 8y agoI 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?)
- MontagFTB 8y agoA sample of the documentation can be found here: http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_write3CT3E/ http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...