[HN Gopher] Show HN: A modern documentation tool for C++ and a r...
       ___________________________________________________________________
        
       Show HN: A modern documentation tool for C++ and a replacement for
       Doxygen
        
       Author : hdoc
       Score  : 21 points
       Date   : 2021-02-05 17:32 UTC (5 hours ago)
        
 (HTM) web link (hdoc.io)
 (TXT) w3m dump (hdoc.io)
        
       | vietjtnguyen wrote:
       | I'm surprised there isn't cross-linking amongst types? If the
       | function listing is `Foo bar(const Baz& x) const` I'd expect
       | `Foo` and `Baz` to be links to those type definitions.
        
         | hdoc wrote:
         | Yes, this is one of the many improvements we plan on adding
         | soon. It was cut from the MVP because we wanted to ensure that
         | it was 100% accurate. Complex code bases can be ambiguous and
         | it would be a disservice if the user clicked on one of these
         | crosslinks and it took them to the wrong symbol.
        
       | hdoc wrote:
       | C++ is falling behind in the quality of documentation output
       | compared to what tools like rustdoc, ReadTheDocs, and godoc
       | generate. Getting good output from existing C++ tools requires
       | disproportionate effort that could be better spent elsewhere.
       | Furthermore, existing tools have a hard time dealing with modern
       | C++.
       | 
       | We made hdoc to solve these problems: prioritizing the quality of
       | output, making the developer experience seamless, and retaining
       | compatibility with existing best practices.
       | 
       | hdoc lets you generate reference API documentation and put
       | supporting guides, tutorials, how-tos right alongside your other
       | docs. We have a sample of what hdoc's output for LLVM+Clang:
       | https://docs.hdoc.io/hdoc/llvm-project/. The source for the repo
       | is available here: https://github.com/hdoc/llvm-project/
       | 
       | Use the code HDOC-HN-LAUNCH for your first three months free when
       | you sign up. 5 codes are available.
        
       | HaoZeke wrote:
       | I've been programming and documenting large projects with sphinx
       | and doxygen for years now and I really don't see the appeal or
       | the problem this solves. Bad documentation is because of lazy
       | programmers. Nothing more, nothing less. If someone is actually
       | able to keep up with the myriad changing C++ standards, not to
       | mention testing practices and frameworks, documentation is not
       | hard in comparison at all. What is often missing is incentives to
       | write documentation, again not something this solves. As for
       | markdown, that's easy to implement with Sphinx anyway. I wrote a
       | series of posts on documenting modern c++ a while ago [1]. There
       | are some fantastic free tools out there, which also allow
       | doctests.
       | 
       | [1] https://rgoswami.me/posts/doc-cpp-dox-sph-exhale/
        
       | [deleted]
        
       | dvfjsdhgfv wrote:
       | At first sight, it looks more modern than Doxygen. But a tool is
       | just a tool, and what really counts is the quality of the
       | documentation itself. Entries like this one are not very useful:
       | 
       | https://docs.hdoc.io/hdoc/llvm-project/fBE2A174F6C7A57F0.htm...
        
         | hdoc wrote:
         | LLVM/Clang are generally well-documented but there are places
         | that don't have great coverage.
         | 
         | Unfortunately tools are only part of the solution. Our goal
         | with hdoc is to make writing documentation easier and to make
         | it easier to create great/cohesive output. If engineers
         | perceive writing documentation as too laborious they'll be
         | unlikely to do it, so we hope that hdoc's workflow and results
         | help.
        
       | bxparks wrote:
       | Took me a while to find the markup supported by hdoc:
       | https://hdoc.io/docs/features/api-docs/
       | 
       | "hdoc supports a small subset of Doxygen's commands. hdoc
       | supports both the @ and \ conventions for commands, meaning you
       | can use @brief or \brief interchangeably."
       | 
       | As far as I can tell, it supports just 3 commands: @brief,
       | @param, @returns. Any plans to support @tparam for template
       | parameters? It's the one other doxygen command that I use
       | frequently for C++ code.
        
         | hdoc wrote:
         | When we originally implemented the Doxygen command support we
         | looked at the most used commands in the code bases we profiled,
         | and settled on about five, which we cut down to those three.
         | Support for more commands is on the roadmap as we look to cover
         | more of the Doxygen spec. This is a reasonable thing to have
         | that many people would find useful, we just didn't focus on it
         | for the MVP.
        
       ___________________________________________________________________
       (page generated 2021-02-05 23:02 UTC)