Dear colleagues,
We are open to scientific collaborations or to engage a (paid) consultant for a clang project, in the wider context of the VINCIA collaboration for LHC Physics (vincia.hepforge.org).
Basically, we want to extract special comments from the clang AST together with their context (where are they?). That information will be used to generate a high-level (human-like) flowchart of our code. It is a similar spirit to Doxygen, but here we want activity diagrams as the outcome.
The most complete visual presentation of the project is here:
https://dl.dropboxusercontent.com/u/36372825/current/index.html
I can also quote a specific example, which illustrates the kind of difficulties that we face:
Take a look at ASTContext::getRawCommentForDeclNoCache(). Given a
Decl, it gets its source location and does a binary search over all
comments in the translation unit, trying to find the last comment that
is before the given source location. After that, it checks if there
are any other decls between the comment and the decl source location.
If there are no other decls -- then the comment is attached to the
decl. All other functions that call getRawCommentForDeclNoCache()
implement the cache. The main entry point (the function that users
should call) is getCommentForDecl().
In your case, a similar strategy is applicable for statements.
Dmitri
Hello, and thanks for the reply, Dimitri.
You give me half of a solution: as you point out, we would need to attach comments to statements.
Is there any developper that would be willing to do such an extension as you propose:
ASTContext::getRawCommentForStmtNoCache()
getCommentForStmt()
Alternatively, how feasible you see that we could implement such an extension (novel to clang, physicist) and that it be maintained?!
Regards,
Juan
Quite a few other developers have asked the same question (if Clang
can attach comments to statements) during past year, but eventually
did not send patches. Nevertheless, this shows that community is
interested in such functionality.
I would not call this hard to implement, but this is not a trivial
change either: you will need to learn at least about Clang's AST,
source location model (and how it interacts with the macros), lexer
and parser architecture. In addition to implementing the feature, you
will also need to design a way to test these APIs *in clang tree*
(without your tool) and write the tests.
Dmitri
I don't think that adding maintenance burden to clang for each new
documentation format is sustainable anyway. Best to take advantage of
modular/library-based design and keep these kinds of tools out of tree.
-- Sean Silva
Hi Sean,
I was not suggesting to add this specific parsing code to Clang --
this is something that should be built in a tool that uses Clang as a
library. I was talking about attaching raw comments to Stmts as a
low-level building block to enable Stmt comment parsing, for any
syntax used in the comment.
Dmitri
Hi Sean
Could you please clarify what you mean? I don't think anyone is
proposing to put Juan Jose's tool in-tree. The proposal is to add a
mechanism for retrieving comments immediately preceding a statement --
would that be something you'd accept in-tree?
Thanks,
Dave.
>
>> > Hello, and thanks for the reply, Dimitri.
>> >
>> > You give me half of a solution: as you point out, we would need to
attach comments to statements.
>> >
>> > Is there any developper that would be willing to do such an extension
as you propose:
>> > ASTContext::getRawCommentForStmtNoCache()
>> > getCommentForStmt()
>> >
>> > Alternatively, how feasible you see that we could implement such an
extension (novel to clang, physicist) and that it be maintained?!
>>
>> Quite a few other developers have asked the same question (if Clang
>> can attach comments to statements) during past year, but eventually
>> did not send patches. Nevertheless, this shows that community is
>> interested in such functionality.
>>
>> I would not call this hard to implement, but this is not a trivial
>> change either: you will need to learn at least about Clang's AST,
>> source location model (and how it interacts with the macros), lexer
>> and parser architecture. In addition to implementing the feature, you
>> will also need to design a way to test these APIs *in clang tree*
>> (without your tool) and write the tests.
>
> I don't think that adding maintenance burden to clang for each new
documentation format is sustainable anyway. Best to take advantage of
modular/library-based design and keep these kinds of tools out of tree.
Hi Sean
Could you please clarify what you mean? I don't think anyone is
proposing to put Juan Jose's tool in-tree. The proposal is to add a
mechanism for retrieving comments immediately preceding a statement --
would that be something you'd accept in-tree?
See my response to Dmitri.
-- Sean Silva