Skip to content

Commit

Permalink
chore: Diagnostics in parseJavadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@vinniefalco
vinniefalco committed Jul 9, 2023
1 parent caf0347 commit dd79d58
Show file tree
Hide file tree
Showing 7 changed files with 273 additions and 47 deletions.
3 changes: 2 additions & 1 deletion docs/modules/ROOT/nav.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
* xref:index.adoc[]
* xref:install.adoc[]
* xref:design-notes.adoc[]
* xref:usage.adoc[]
* xref:commands.adoc[]
* xref:design-notes.adoc[]
* xref:contribute.adoc[]
* xref:license.adoc[]
14 changes: 14 additions & 0 deletions docs/modules/ROOT/pages/commands.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
= Commands

These are the Doxygen-style "@" commands recognized by MrDox:

== Italics / Emphasis
[]
----
@a [word]
@e [word]
@em [word]
<em>[text]</em>
----

2 changes: 1 addition & 1 deletion lib/AST/ASTVisitor.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -998,7 +998,7 @@ class ASTVisitor
// ASTContext::getCommentForDecl instead
RawComment* RC =
D->getASTContext().getRawCommentForDeclNoCache(D);
parseJavadoc(javadoc, RC, D, config_);
parseJavadoc(javadoc, RC, D, config_, diags_);
}

//------------------------------------------------
Expand Down
269 changes: 249 additions & 20 deletions lib/AST/ParseJavadoc.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,215 @@
#include <clang/Basic/SourceManager.h>
#include <llvm/Support/JSON.h>

/*
Comment Types
/* Doxygen commands
Italics \a
Italics \e
Italics \em
\addindex
\addtogroup
\anchor
\arg
\attention
\author
\authors
\b
\brief
\bug
\c
\callergraph
\callgraph
\category
\cite
\class
\code
\concept
\cond
\copybrief
\copydetails
\copydoc
\copyright
\date
\def
\defgroup
\deprecated
\details
\diafile
\dir
\docbookinclude
\docbookonly
\dontinclude
\dot
\dotfile
\doxyconfig
\else
\elseif
\emoji
\endcode
\endcond
\enddocbookonly
\enddot
\endhtmlonly
\endif
\endinternal
\endlatexonly
\endlink
\endmanonly
\endmsc
\endparblock
\endrtfonly
\endsecreflist
\endverbatim
\enduml
\endxmlonly
\enum
\example
\exception
\extends
\f(
\f)
\f$
\f[
\f]
\f{
\f}
\file
\fileinfo
\fn
\headerfile
\hidecallergraph
\hidecallgraph
\hiderefby
\hiderefs
\hideinitializer
\htmlinclude
\htmlonly
\idlexcept
\if
\ifnot
\image
\implements
\include
\includedoc
\includelineno
\ingroup
\internal
\invariant
\interface
\latexinclude
\latexonly
\li
\line
\lineinfo
\link
\mainpage
\maninclude
\manonly
\memberof
\msc
\mscfile
\n
\name
\namespace
\noop
\nosubgrouping
\note
\overload
\p
\package
\page
\par
\paragraph
\param
\parblock
\post
\pre
\private
\privatesection
\property
\protected
\protectedsection
\protocol
\public
\publicsection
\pure
\qualifier
\raisewarning
\ref
\refitem
\related
\relates
\relatedalso
\relatesalso
\remark
\remarks
\result
\return
\returns
\retval
\rtfinclude
\rtfonly
\sa
\secreflist
\section
\see
\short
\showdate
\showinitializer
\showrefby
\showrefs
\since
\skip
\skipline
\snippet
\snippetdoc
\snippetlineno
\static
\startuml
\struct
\subpage
\subsection
\subsubsection
\tableofcontents
\test
\throw
\throws
\todo
\tparam
\typedef
\union
\until
\var
\verbatim
\verbinclude
\version
\vhdlflow
\warning
\weakgroup
\xmlinclude
\xmlonly
\xrefitem
\$
\@
\\
\&
\~
\<
\=
\>
\#
\%
\"
\.
\::
\|
\--
\---
--------------------------------------------------
AST Types
Comment
abstract base for all comments
Expand Down Expand Up @@ -83,10 +290,10 @@
VerbatimBlockLineComment : Comment
A line of text contained in a verbatim block.
*/
/*
BlockCommandComment
Always has one child of type ParagraphComment child?
*/

namespace clang {
Expand All @@ -106,6 +313,7 @@ class JavadocVisitor
SourceManager const& sm_;
FullComment const* FC_;
Javadoc jd_;
Diagnostics& diags_;
doc::List<doc::Param> params_;
doc::Paragraph* paragraph_ = nullptr;
std::size_t htmlTagNesting_ = 0;
Expand All @@ -117,7 +325,8 @@ class JavadocVisitor

public:
JavadocVisitor(
RawComment const*, Decl const*, Config const&);
RawComment const*, Decl const*,
Config const&, Diagnostics&);
Javadoc build();

void visitComment(Comment const* C);
Expand Down Expand Up @@ -201,11 +410,13 @@ JavadocVisitor::
JavadocVisitor(
RawComment const* RC,
Decl const* D,
Config const& config)
Config const& config,
Diagnostics& diags)
: config_(config)
, ctx_(D->getASTContext())
, sm_(ctx_.getSourceManager())
, FC_(RC->parse(D->getASTContext(), nullptr, D))
, diags_(diags)
{
}

Expand Down Expand Up @@ -331,6 +542,20 @@ JavadocVisitor::
visitInlineCommandComment(
InlineCommandComment const* C)
{
auto const* cmd = ctx_
.getCommentCommandTraits()
.getCommandInfo(C->getCommandID());

if( cmd->getID() == CommandTraits::KCI_copybrief ||
cmd->getID() == CommandTraits::KCI_copydetails ||
cmd->getID() == CommandTraits::KCI_copydoc)
{
if(C->getNumArgs() != 1)
{
// throw an error
}
}

doc::Style style(doc::Style::none);
switch (C->getRenderKind())
{
Expand Down Expand Up @@ -420,7 +645,7 @@ visitBlockCommandComment(
jd_.emplace_back(std::move(returns));
return;
}
if(cmd->getID() == CommandTraits::KCI_note)
if(cmd->getID() == CommandTraits::KCI_note)
{
doc::Admonition paragraph(doc::Admonish::note);
Scope scope(paragraph, paragraph_);
Expand Down Expand Up @@ -714,23 +939,27 @@ parseJavadoc(
std::unique_ptr<Javadoc>& jd,
RawComment* RC,
Decl const* D,
Config const& config)
Config const& config,
Diagnostics& diags)
{
if(RC)
if(! RC)
{
RC->setAttached();
MRDOX_ASSERT(! jd);
return;
}

auto result = JavadocVisitor(RC, D, config).build();
RC->setAttached();

if(jd == nullptr)
{
jd = std::make_unique<Javadoc>(std::move(result));
}
else if(*jd != result)
{
// merge
jd->append(std::move(result));
}
auto result = JavadocVisitor(RC, D, config, diags).build();

if(jd == nullptr)
{
jd = std::make_unique<Javadoc>(std::move(result));
}
else if(*jd != result)
{
// merge
jd->append(std::move(result));
}
}

Expand Down
4 changes: 3 additions & 1 deletion lib/AST/ParseJavadoc.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
#ifndef MRDOX_TOOL_AST_PARSEJAVADOC_HPP
#define MRDOX_TOOL_AST_PARSEJAVADOC_HPP

#include "Lib/Diagnostics.hpp"
#include <mrdox/Platform.hpp>
#include <mrdox/Config.hpp>
#include <mrdox/Metadata/Javadoc.hpp>
Expand Down Expand Up @@ -40,7 +41,8 @@ parseJavadoc(
std::unique_ptr<Javadoc>& jd,
RawComment* RC,
Decl const* D,
Config const& config);
Config const& config,
Diagnostics& diags);

} // mrdox
} // clang
Expand Down
8 changes: 1 addition & 7 deletions test-files/adoc/test.cpp
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1 @@
/** brief
desc
@warning caution
*/
void f();
struct T {};
Loading

0 comments on commit dd79d58

Please sign in to comment.