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

[Philipp Moeller]

On Mar 14, 2014 9:23 PM, "Dmitri Gribenko" <gribozavr at gmail.com> wrote:
>
> 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.

This seems really important. Linking is one of the quirkiest areas of
Doxygen and getting it really right would be great.

> ... 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.

Interesting. Is there some other part of clang that uses such files? How
would I know to which code base to attach them? Or do we leave setting this
up to the user? Is there a preference for certain data formats in clang?

> 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>*/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20140314/06c56db3/attachment.html>