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.
> 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?
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.
> 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.
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.
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.
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.
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.
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.
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.
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?)
30 comments
[ 4.7 ms ] story [ 72.6 ms ] thread> 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.
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...
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.
The above documentation is derived from the following source file: https://github.com/stlab/libraries/blob/develop/stlab/copy_o...
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
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.
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.
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.
no, that's terrible. How do you do when you don't want to install the source of every lib you use ?
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.
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.
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?)