Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

extensions: overhaul javadoc/doxygen comment parsing #216

Merged
merged 4 commits into from
Nov 17, 2023
Merged

extensions: overhaul javadoc/doxygen comment parsing #216

merged 4 commits into from
Nov 17, 2023

Commits on Nov 17, 2023

  1. extensions: overhaul javadoc/doxygen comment parsing 

    Full javadoc/doxygen compatibility has never been a goal for
hawkmoth. We've always promoted using pure reStructuredText and Sphinx,
because it avoids any problematic conversions. If you want all the bells
and whistles of doxygen, you should use doxygen.

However, we have to acknowledge there are a lot of codebases full of
javadoc/doxygen style documentation comments, and a lot of people who
are familiar with that style of code documentation. Requiring the use of
reStructuredText to even try hawkmoth can be quite a hurdle.

To that end, we've always had a rudimentary regex based conversion
available. But let's face the fact, is too simple, and too difficult to
maintain or extend as it is.

Try to find a middle ground with an improved parser that understands
paragraphs, inline markup, code blocks, and the like. Make it easier to
extend. Recognize all doxygen commands (more than 180 of them!), even
though we only implement a handful, making it possible to warn about the
unimplemented ones (this is for future improvement, not done yet).
    @jnikula
    jnikula committed Nov 17, 2023
    Configuration menu
    Copy the full SHA
    1c70aa9 View commit details
    Browse the repository at this point in the history

  2. examples: update the javadoc/doxygen example 

    Improve the description of the javadoc builtin extension. This also
expands the tests slightly.
    @jnikula
    jnikula committed Nov 17, 2023
    Configuration menu
    Copy the full SHA
    54ca33e View commit details
    Browse the repository at this point in the history

  3. doc: clarify the transform option for built-in extensions

    @jnikula
    jnikula committed Nov 17, 2023
    Configuration menu
    Copy the full SHA
    75f24e5 View commit details
    Browse the repository at this point in the history

  4. doc: better describe what to expect from the javadoc extension 

    It's a little better than "rudimentary at best", but still keep the
expectations at bay.
    @jnikula
    jnikula committed Nov 17, 2023
    Configuration menu
    Copy the full SHA
    b2ed2d2 View commit details
    Browse the repository at this point in the history