lawmurray / doxide Goto Github PK

A function that returns a reference type, e.g. int f(int x, int y); does not get included in the documentation.

It would be useful for migration purposes if doxide supported doxygen-style C++ // comments, namely:

• //! or /// introduces documentation block comments
• //!< or ///< introduces member comments, after the member

Conversion operators such as the following are not extracted:

struct Example {
  /**
   * Test.
   */
  operator int();
};

Hello,

I'm trying to compile the program for Fedora 39, as it is not (yet?) in the repository. I used the instructions from the README and went:

git clone https://github.com/lawmurray/doxide --recurse-submodules
cd doxide
mkdir build
cd build
cmake ..
cmake --build .

Sadly, the last command resulted in an error on the very first step:

[  8%] Building C object CMakeFiles/doxide.dir/contrib/tree-sitter/lib/src/lib.c.o
In file included from /home/pierre/code/doxide/contrib/tree-sitter/lib/src/././unicode.h:13,
                 from /home/pierre/code/doxide/contrib/tree-sitter/lib/src/./lexer.c:5,
                 from /home/pierre/code/doxide/contrib/tree-sitter/lib/src/lib.c:11:
/home/pierre/code/doxide/contrib/tree-sitter/lib/src/././unicode/utf8.h:37:10: fatal error: unicode/umachine.h: No such file or directory
   37 | #include "unicode/umachine.h"
      |          ^~~~~~~~~~~~~~~~~~~~
compilation terminated.
gmake[2]: *** [CMakeFiles/doxide.dir/build.make:76: CMakeFiles/doxide.dir/contrib/tree-sitter/lib/src/lib.c.o] Error 1
gmake[1]: *** [CMakeFiles/Makefile2:83: CMakeFiles/doxide.dir/all] Error 2
gmake: *** [Makefile:156: all] Error 2

I checked, and umachine.h is where it is supposed to be, so I'm assuming that I did something wrong in previous steps. Would you have any idea?

Thanks in advance :)

Having an option for verbose output could be helpful, for example outputting the line that caused the parse error.
I am encountering a lot of parse errors and would like to know if i can adjust my code to reduce them.

It seems like the short summary of an entity is determined by the text before the first '.' character. If the documentation comment doesn't have one (e.g. /** Some field */) it doesn't get a summary at all.

This is kind of simple to work around by just adding a '.', but conversely it also stops the summary at the first period in cases where maybe multiple sentences should be in the summary. Or, as in my case, this: Extension of the output filename, including dot '.' character.

Maybe defining the summary as the first line of the documentation comment could be better? That was my initial expectation at least, similar to e.g. git commit messages.

A struct or class nested inside another struct/class is not included in the output documentation, e.g:

/** A class */
class OuterClass
{
  /** An inner class - not recognized by Doxide */
  class InnerClass
  {
  };
};

Linked to #35

In C (it is not the case in C++), it is customary to do

typedef struct stuff_ {
  int a;
} stuff;

If doxide encounter such construct, it seems to be creating a page for struct stuff_ and forgets about the typedef. It would probably be possible to automatically duplicate this info and create an corresponding entry for the corresponding typedef structy stuff_ stuff.

However, that's a C specific stuff, so I understand if it is not a priority :)

With Windows support imminent (see #3), it would be great to see a Chocolatey package for Doxide. There are even packages available for MkDocs and Material for MkDocs already, which should make Doxide installation on Windows as simple as:

choco install doxide mkdocs mkdocs-material

Happy for anyone to have a look at this.

Add packages for major Linux distributions.

The approach will be to replicate the CircleCI pipeline used by Birch to build and sign packages and repositories, for installation with apt, yum, dnf, zypper, etc. Distributions will include Debian, Ubuntu, Fedora, openSUSE, Mageia. Packages will be updated automatically when a new version is tagged.

I'll handle it, but please post requests for specific Linux distributions to support, and I'll see what I can do.

Hello. Thanks for good tool.

I wrote following comments using itemization in header file.

- vector2 : time parameters of filter
    - sampling period [s]
    - time constant [s]

When I run doxide build, I got following result in converted markdown file.

- vector2 : time parameters of filter
- sampling period [s]  <-- nest is deleted!
- time constant [s]      <-- nest is deleted!

Did I write something wrong?
If you know a solution, please let me know.

Thanks in advance.

Doxide omits entities with names that include unicode characters, e.g. double β.

This is due to lack of support in earlier versions of tree-sitter-cpp, but support is available since v0.20.2. The submodule in Doxide just needs updating.

Doxide currently uses POSIX getopt_long() to parse command-line options. This should be replaced with something portable, such as CLI11, to enable Windows support.

I want to make a bug report.

If one use doxide on this code:

/**
* That's a test.
 */
struct test_ {
  /// A first variable
  int a;
  
  /// a second variable
  FILE* f;
};

The second variable does not get documented.
I think the problem comes from the use of pointers, since it also does not work with, say, char*.
More strange, while using this code:

/**
* That's a test.
 */
struct test_ {
  /// A first variable
  int a;
  
  /// a second variable
  FILE* f;
};

typedef struct test_ test; // yeah, it is C, typedef are not automatic

... Then the info for FILE* f appears in the description of the typedef.

Using markdown headers within a doc-comment does not render the header correctly. This is very similar to #38 in that using /** ... */ works but /// does not but for the header instead. Below the same example code as in that case.

namespace example {

/** First function
 *
 * This one uses block comments and multiple paragraphs and such can be used.
 *
 * #### Example
 *
 * ```c++
 * first();
 * ```
 */
void first();

/// Second function
///
/// This one uses single-line comments and the paragraphs are broken.
///
/// #### Example
///
/// ```c++
/// second();
/// ```
void second();

} // namespace example

This renders the header correctly for first but not for second. From what I can see, the only difference in the rendered markdown is an extra space before the markdown in the instance that doesn't work.

CircleCI now supports Docker executors on ARM, which ought to allow building of ARM packages.

Doxide packages are currently built through the download.indii.org repository, see lawmurray/download.indii.org#1.

Ran into another problem.

While i was trying to clone a repo with the build html pages, it was failing, because of a too long creation path:

public/hg/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterStorage/index.html

So I checked the created docs directory of doxide and found the same folder structure with the related markdown files and sub-folders.

~/git/docs/hg/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterTypeStorage/ConstantNodeParameterStorage.md

The related source code:`

typedef _STD variant<
    /**/
    ConstantNodeParameterTypeStorage<NodeLinkValueType::u8>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::u16>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::u32>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::u64>::type,
    /**/
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f32>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f64>::type,
    /**/
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f32vec2>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f32vec3>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f32vec4>::type,
    /**/
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f32mat2x2>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f32mat3x3>::type,
    ConstantNodeParameterTypeStorage<NodeLinkValueType::f32mat4x4>::type
    /**/
    //ConstantNodeParameterTypeStorage<NodeLinkValueType::color>::type // Does already exists as `f32vec4`
> ConstantNodeParameterStorage;

So I guess the variant is a problem :?
Anyway, if you need more of the source code, msg me again.

Sorry for the inconvenience.

In some situations, operators appear with their body, not just signature, e.g.

The formatting (italics) also suggests that some characters are not being correctly sanitized for HTML.

There is a PKGBUILD in the repository as a start, although this will need testing.

Consider this issue a place for new @command requests. Please reply with suggested new commands or requests for existing Doxygen commands that would help with migration of an existing codebase (e.g. @copydoc).

I have the following yaml file

groups:
  - name: A
    title: A api
    description: A part
    groups:
      - name: B
         title: B api
         description: B part
         groups:
           - name: C
              title: C api
              description: C part

and in a class of the C subsubgroup I have written

/**
 * @ingroup A B C
 */

But the documentation is generated in the A group page and not in the C sub sub group page.

Please, how can I manage hierarchy with accuracy?

While I totally get why struct and class gets their own separate page,

typedef struct suff_ stuff;

... Also result in a separated page, which does not contain much. I think this should go on the same page as, say, the macros and functions, just in a separate "typedef" section.

Doxide currently uses POSIX glob() to handle file patterns in configuration files. This should be replaced with something portable, such as a combination of std::filesystem::recursive_directory_iterator and std::regex, to enable Windows support.

The suggestion would be to add a new section to the docs, just before types, say, to document concepts.

We'd like to support Windows. This is a ticket to consolidate prerequisites and solicit feedback from Windows users. If you have tested out on Windows or would like to have a go at one or more of these, please let us know here!

• #1
• #2

With Python and Rust I can put examples into my doc-comments and run them as tests via pytest or cargo test respectively. Is there any chance of Doxide helping to extract these examples from the doc-comments and generate unit-test files from them?

This would obviously be more complex for C++ because nobody can agree on a single unit test framework to use. Having a configurable header and footer for the output files, and for each test case, might be enough.

You'd also probably want something like Rust has where only some lines of the code block are shown in documentation, but all of them are output to the test file. Rust uses a # prefix on lines not included in the docs, but that would be awkward for C++.

#include directives would need to be extracted and moved to the top of the output test file.

Add Homebrew tap and packages for macOS.

The approach will be to replicate the CircleCI pipeline used by Birch to update the tap when a new version is tagged.

It would be good to support access specifiers, i.e. public, protected and private in classes.

Suggestions welcome on how to handle this from a presentation perspective, e.g. tagging each entity with its access specifier (if any), or grouping members of a class by access specifier.

I just tried out to build the documentation for my project and the process crashed while trying to generate files for one of my more complex template classes.

terminate called after throwing an instance of 'std::filesystem::__cxx11::filesystem_error'
  what():  filesystem error: cannot create directories: File name too long [docs/hg/LoaderChain_u003c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020RequestType__u002c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020ResponseType__u002c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020StageRefTypes__u002c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020CacheStageType__u002c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020FeedbackStageType__u002c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020TransformerStageType__u002c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020SourceLoaderType__u002c_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020true_u000a_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u0020_u003e]
Aborted (core dumped)

template <
        IsRequestValueType RequestType_,
        IsResponseValueType ResponseType_ = ResourceBase,
        typename StageRefTypes_ = MetaTypeWrapperList<
            _STD type_identity_t,
            _STD type_identity_t,
            _STD type_identity_t,
            sptr
        >,
        class CacheStageType_ = Cache<RequestType_, ResponseType_>,
        class FeedbackStageType_ = Feedback<RequestType_, ResponseType_>,
        class TransformerStageType_ = Transformer<RequestType_, ResponseType_>,
        class SourceLoaderType_ = SourceLoader,
        bool Streamable_ = assets::IsStreamableAsset<RequestType_>>
class LoaderChain :
    public LoaderChainBase<
        RequestType_, ResponseType_, StageRefTypes_,
        CacheStageType_, FeedbackStageType_, TransformerStageType_, SourceLoaderType_> { ... };

Don't know whether this helps, but if you need further source code or information, just msg me.

Currently the doxide.exe executable and doxide-installer.exe installer are not code signed on Windows, which triggers Windows Defender. Ideally we would set up code signing in the release pipeline.

I've found I can't use paragraphs when inside /// doc-comments. Using this header file:

namespace example {

/** First function
 *
 * This one uses block comments and multiple paragraphs and such can be used.
 *
 * #### Example
 *
 * ```c++
 * first();
 * ```
 */
void first();

/// Second function
///
/// This one uses single-line comments and the paragraphs are broken.
///
/// #### Example
///
/// ```c++
/// second();
/// ```
void second();

} // namespace example

The documentation for the first function is correct, but the second does not, getting all its paragraphs jammed together:

This might be Windows specific, as I haven't been able to test it on Linux. It doesn't seem to be end-of-line related though.

Add automatic linking to entity signatures. When the signature appears in the docs as, for example:

TypeA f(const TypeB& b, const TypeC& c);

the types TypeA, TypeB and TypeC ought to link to their respective documentation pages, if they exist. An example is available in the Birch documentation for the Buffer class, noting that known types are linked throughout¹.

Ideally this would be achieved by using the existing Tree-sitter parser to pluck out type identifiers and link them if recognized. If that proves too tricky, a fallback would be regular expressions to find and replace identifiers that are recognized as types.

Some further context. The Doxygen approach to automatic link generation is as follows:

All words in the documentation that correspond to a documented class and contain at least one non-lower case character will automatically be replaced by a link to the page containing the documentation of the class. If you want to prevent that a word that corresponds to a documented class is replaced by a link you should put a % in front of the word.

Personally, I have always found this too aggressive, and end up using a lot of % to prevent Doxygen from creating links, which I can typically only identify when editing the final result. This becomes laborious. I would prefer that Doxide automatically link in signatures, as suggested in this ticket, but that it does not create automatic links in the documentation itself. Rather, links can be added where appropriate with Markdown, or in future, perhaps a @command can be added for the purpose.

Ref e.g. #7 , it would be useful to add a --quiet and/or --verbose flag to doxide to control the level of reporting. Warnings for autocorrections and unrecognized commands might be silenced in quiet mode, for example.

Hello. Thanks for sharing the tool with the community. Looks very promising.

There's an issue with the presentation of the escapee member variable. It looks like this:

Attempt to move a member out of its class with but should remain inClassWithMembers`.

But the expected presentation is

Attempt to move a member out of its class with @ingroup, but should remain in ClassWithMembers.

according to the sources:

I get a segfault when parsing my library ...

#10 0x00005555555a5b62 in std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >::_M_replace (
    this=0x7fffffffd820, __pos=0, __len1=0, 
    __s=0x555555892e32 "Calculates a global bilevel image\n     * @param src input image\n     * @param dest output image\n     * @param threshold threshold value (@see Otsu)\n     * @param flags\n     */\n    template <typename A"..., 
    __len2=18446650248713916878) at /usr/include/c++/13.1.1/bits/basic_string.tcc:511
#11 0x00005555555a4d63 in std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >::replace (
    this=0x7fffffffd820, __pos=0, __n1=0, 
    __s=0x555555892e32 "Calculates a global bilevel image\n     * @param src input image\n     * @param dest output image\n     * @param threshold threshold value (@see Otsu)\n     * @param flags\n     */\n    template <typename A"..., 
    __n2=18446650248713916878) at /usr/include/c++/13.1.1/bits/basic_string.h:2209
#12 0x00005555555a4c78 in std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >::replace (
    this=0x7fffffffd820, __i1=0 '\000', __i2=0 '\000', 
    __k1=0x555555892e32 "Calculates a global bilevel image\n     * @param src input image\n     * @param dest output image\n     * @param threshold threshold value (@see Otsu)\n     * @param flags\n     */\n    template <typename A"..., __k2=0x0)
    at /usr/include/c++/13.1.1/bits/basic_string.h:2418
#13 0x00005555555a3510 in std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >::append<char const*, void> (this=0x7fffffffd820, 
    __first=0x555555892e32 "Calculates a global bilevel image\n     * @param src input image\n     * @param dest output image\n     * @param threshold threshold value (@see Otsu)\n     * @param flags\n     */\n    template <typename A"..., __last=0x0)
    at /usr/include/c++/13.1.1/bits/basic_string.h:1520
#14 0x000055555559f7d2 in Parser::translate (this=0x7fffffffda50, 
    comment="/**\n     * @brief Calculates a global bilevel image\n     * @param src input image\n     * @param dest output image\n     * @param threshold threshold value (@see Otsu)\n     * @param flags\n     */", entity=...)
    at /home/hartmut/Code/doxide/src/parser/Parser.cpp:226
#15 0x000055555559ddc5 in Parser::parse (this=0x7fffffffda50, 
    source="/* vim: set tabstop=4:softtabstop=4:shiftwidth=4:noexpandtab */\n/*\n * SSTT - Simplified Spatial Target Tracker\n *\n * © Copyright 2007-2023 Hartmut Seichter\n */\n#ifndef SSTT_CORE_THRESHOLD_HPP\n#define"..., global=...)
    at /home/hartmut/Code/doxide/src/parser/Parser.cpp:58
#16 0x00005555555eb1b5 in Driver::build (this=0x7fffffffdb40) at /home/hartmut/Code/doxide/src/Driver.cpp:150
#17 0x000055555559c21c in main (argc=2, argv=0x7fffffffde98) at /home/hartmut/Code/doxide/src/doxide.cpp:11

Header looks like this:

/* vim: set tabstop=4:softtabstop=4:shiftwidth=4:noexpandtab */
/*
 * SSTT - Simplified Spatial Target Tracker
 *
 * © Copyright 2007-2023 Hartmut Seichter
 */
#ifndef SSTT_CORE_THRESHOLD_HPP
#define SSTT_CORE_THRESHOLD_HPP

#include <sstt/core/globals.hpp>

namespace sstt::core
{

    /**
     * @brief Calculates a global bilevel image
     * @param src input image
     * @param dest output image
     * @param threshold threshold value (@see Otsu)
     * @param flags
     */
    template <typename ArrayTypeSrc, typename ArrayTypeDst>
    void ThresholdGlobal(ArrayTypeDst &dst,
                         const ArrayTypeSrc &src,
                         auto threshold,
                         auto min_val,
                         auto max_val)

I tried to remove the @otsu reference with no avail.

I noticed that you've started providing release tarballs. Could you please also add the contrib's sources there? I can't run git submodule update, since there's no .git directory.