
Show HN: Hyde – An out-of-line C++ library documentation tool - MontagFTB
https://github.com/adobe/hyde
======
jlg23
> 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
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.

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

~~~
jcelerier
> 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 ?

~~~
kevin_thibedeau
You read the generated docs or get the source.

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

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

input:
[https://raw.githubusercontent.com/stlab/libraries/develop/st...](https://raw.githubusercontent.com/stlab/libraries/develop/stlab/copy_on_write.hpp)

output:
[https://github.com/stlab/stlab.github.io/tree/master/librari...](https://github.com/stlab/stlab.github.io/tree/master/libraries/stlab2Fcopy_on_write.hpp)

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
Your output link just shows a load of JSON to me...

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

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

------
rkagerer
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?)

~~~
MontagFTB
A sample of the documentation can be found here:
[http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...](http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_write3CT3E/)

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

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

------
mempko
Question, any live examples?

~~~
mbel
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

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

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

~~~
MontagFTB
A sample of the kind of documentation it can produce is here:
[http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...](http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_write3CT3E/)

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

------
biII_cosby
They can't keep getting away with it.

