[cfe-dev] [GSoC] Doxygen documentation with clang

[Dmitri Gribenko]

On Tue, Mar 11, 2014 at 1:22 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> On Tue, Mar 11, 2014 at 12:36 PM, Philipp Moeller <bootsarehax at gmail.com> wrote:
>> Dmitri Gribenko <gribozavr at gmail.com>
>> writes:
>>
>>> On Mon, Mar 10, 2014 at 5:59 PM, Philipp Moeller <bootsarehax at gmail.com> wrote:
>>>> For a good application I would like to define a certain set of
>>>> milestones we want to achieve. If you have anything specific in mind,
>>>> please let me know.
>>>
>>> Based on the discussion so far, I think this could be used as a draft plan:
>>>
>>> - attaching comments to macros;
>>> - parsing the reference syntax (recognising that the text from here to
>>> there is a possible reference, which we will need to resolve).
>>> Implementing Comment AST representation for unresolved references.
>>> Designing and implementing the XML representation for unresolved
>>> references.
>>> - resolving links to decls within the TU.  The result should probably
>>> be a Decl* or a USR.  The USR should be available in the XML;

Hi Philipp,

I have discussed this proposal with Argyrios Kyrtzidis today, and we
agreed that it would be best to only include the above points plus the
following point

- defining exactly what kind of information should we retain while
indexing the translation unit in order to be able to resolve (yet
unknown set of) links against it.

... as 'required' in the GSoC proposal, and the work related to DB
mentioned below should be 'opportunity'.

>>> - defining a schema for a DB to store information about possible link
>>> targets (declarations and macros);
>>> - populating DB with information from TUs in the project;
>>> - resolving links to decls cross-TU using the DB.  The result should
>>> be a USR, and maybe the source file name + source location.

About the indexing, Argyrios suggested that it would be best to
decouple the process into two steps:

- indexing info should be produced as a separate file on disk (lets
call the file foo.clangindex)
- the tool can consume *.clangindex files to populate the database.

This separation allows us in future to produce indexing information
during compilation as a sidecar file, so that if the user is building
the project anyway, we don't parse the for indexing and compilation
twice.

What do you think?

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/