A new clang-based documentation tool

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

A new clang-based documentation tool

Sumner, Brian via cfe-dev

Hi there,

 

I’d like to let you know that we’re currently working on a documentation tool as a replacement to Doxygen. It’s all still work in progress, but it’s getting to the point where it will be actually usable for projects. Compared to Doxygen, we’re trying to give some significant improvements with regard to the output and control thereof, as well as improve integration with build systems for incremental builds and distribution. Of course this is all using Clang behind the scenes. Within time, we will be open-sourcing it and will definitely need some hands to keep the project going, as well as to, for example, extend Clang’s Doxygen parser.

 

However, before we get to that point, we are concerned with something slightly off topic: the name, of which the tool currently does not have one. We had ClangDoc/clangdoc in mind, but we’re wondering about the general consensus of naming Clang-based tooling after Clang itself? Is there anything against that?

 

Kind regards,

 

Athos

 

Junior Tools Programmer

Guerrilla

 


_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: A new clang-based documentation tool

Sumner, Brian via cfe-dev
Hi Athos,

  My impression is we usually name the tool with dash in between, like
clang-diff, clang-format, ... etc.
IMHO, clang-doxygen will be good as it remind me it tends to replace doxygen.

Regards,
chenwj

2017-08-01 17:27 GMT+08:00 Athos van Kralingen via cfe-dev
<[hidden email]>:

> Hi there,
>
>
>
> I’d like to let you know that we’re currently working on a documentation
> tool as a replacement to Doxygen. It’s all still work in progress, but it’s
> getting to the point where it will be actually usable for projects. Compared
> to Doxygen, we’re trying to give some significant improvements with regard
> to the output and control thereof, as well as improve integration with build
> systems for incremental builds and distribution. Of course this is all using
> Clang behind the scenes. Within time, we will be open-sourcing it and will
> definitely need some hands to keep the project going, as well as to, for
> example, extend Clang’s Doxygen parser.
>
>
>
> However, before we get to that point, we are concerned with something
> slightly off topic: the name, of which the tool currently does not have one.
> We had ClangDoc/clangdoc in mind, but we’re wondering about the general
> consensus of naming Clang-based tooling after Clang itself? Is there
> anything against that?
>
>
>
> Kind regards,
>
>
>
> Athos
>
>
>
> Junior Tools Programmer
>
> Guerrilla
>
>
>
>
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>



--
Wei-Ren Chen (陳韋任)
Homepage: https://people.cs.nctu.edu.tw/~chenwj
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: A new clang-based documentation tool

Sumner, Brian via cfe-dev
In reply to this post by Sumner, Brian via cfe-dev
By the way, there is a open-source project called DoxyPress which is
also a clang-based doxygen replacement:
https://github.com/copperspice/doxypress

- Raphael

2017-08-01 11:27 GMT+02:00 Athos van Kralingen via cfe-dev
<[hidden email]>:

> Hi there,
>
>
>
> I’d like to let you know that we’re currently working on a documentation
> tool as a replacement to Doxygen. It’s all still work in progress, but it’s
> getting to the point where it will be actually usable for projects. Compared
> to Doxygen, we’re trying to give some significant improvements with regard
> to the output and control thereof, as well as improve integration with build
> systems for incremental builds and distribution. Of course this is all using
> Clang behind the scenes. Within time, we will be open-sourcing it and will
> definitely need some hands to keep the project going, as well as to, for
> example, extend Clang’s Doxygen parser.
>
>
>
> However, before we get to that point, we are concerned with something
> slightly off topic: the name, of which the tool currently does not have one.
> We had ClangDoc/clangdoc in mind, but we’re wondering about the general
> consensus of naming Clang-based tooling after Clang itself? Is there
> anything against that?
>
>
>
> Kind regards,
>
>
>
> Athos
>
>
>
> Junior Tools Programmer
>
> Guerrilla
>
>
>
>
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: A new clang-based documentation tool

Sumner, Brian via cfe-dev
There's also Doxygen, which can also use clang libraries for parsing :)

On Wed, Aug 2, 2017 at 11:58 PM, Raphael Isemann via cfe-dev
<[hidden email]> wrote:

> By the way, there is a open-source project called DoxyPress which is
> also a clang-based doxygen replacement:
> https://github.com/copperspice/doxypress
>
> - Raphael
>
> 2017-08-01 11:27 GMT+02:00 Athos van Kralingen via cfe-dev
> <[hidden email]>:
>> Hi there,
>>
>>
>>
>> I’d like to let you know that we’re currently working on a documentation
>> tool as a replacement to Doxygen. It’s all still work in progress, but it’s
>> getting to the point where it will be actually usable for projects. Compared
>> to Doxygen, we’re trying to give some significant improvements with regard
>> to the output and control thereof, as well as improve integration with build
>> systems for incremental builds and distribution. Of course this is all using
>> Clang behind the scenes. Within time, we will be open-sourcing it and will
>> definitely need some hands to keep the project going, as well as to, for
>> example, extend Clang’s Doxygen parser.
>>
>>
>>
>> However, before we get to that point, we are concerned with something
>> slightly off topic: the name, of which the tool currently does not have one.
>> We had ClangDoc/clangdoc in mind, but we’re wondering about the general
>> consensus of naming Clang-based tooling after Clang itself? Is there
>> anything against that?
>>
>>
>>
>> Kind regards,
>>
>>
>>
>> Athos
>>
>>
>>
>> Junior Tools Programmer
>>
>> Guerrilla
>>
>>
>>
>>
>> _______________________________________________
>> cfe-dev mailing list
>> [hidden email]
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>>
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev



--
GCS a+ e++ d- C++ ULS$ L+$ !E- W++ P+++$ w++$ tv+ b++ DI D++ 5++
The Tao of math: The numbers you can count are not the real numbers.
Life is complex, with real and imaginary parts.
"Ok, it boots. Which means it must be bug-free and perfect. " -- Linus Torvalds
"People disagree with me. I just ignore them." -- Linus Torvalds
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: A new clang-based documentation tool

Sumner, Brian via cfe-dev
Thanks for the heads up, but we were aware of those options and how far we could get with Doxygen itself. It being clang-based was not really the motivation behind the project; we just started fresh and Clang was by far the best option as a parser, hence we didn't simply opt for Doxygen or a modification thereof. The same goes for DoxyPress of course, as it is a fork of Doxygen, making it not much different.

Our tool is a Doxygen replacement to us (and perhaps others eventually), but it is definitely very different in aspects such as output, configuration and with that, customization. We simply refer to Doxygen due to its seemingly dominant presence for creating c++ documentation.

Also, if all goes well, it should also be more feasible to integrate into build systems, which gives, especially us, some options for scaling more easily too. A not unwelcome addition I'd say. There's some things left to do before that, though, but we'll make sure to keep this up to date as development progresses.

- Athos

-----Original Message-----
From: Csaba Raduly [mailto:[hidden email]]
Sent: Thursday, August 3, 2017 9:38 AM
To: Raphael Isemann <[hidden email]>
Cc: Athos van Kralingen <[hidden email]>; [hidden email]
Subject: Re: [cfe-dev] A new clang-based documentation tool

There's also Doxygen, which can also use clang libraries for parsing :)

On Wed, Aug 2, 2017 at 11:58 PM, Raphael Isemann via cfe-dev <[hidden email]> wrote:

> By the way, there is a open-source project called DoxyPress which is
> also a clang-based doxygen replacement:
> https://github.com/copperspice/doxypress
>
> - Raphael
>
> 2017-08-01 11:27 GMT+02:00 Athos van Kralingen via cfe-dev
> <[hidden email]>:
>> Hi there,
>>
>>
>>
>> I’d like to let you know that we’re currently working on a
>> documentation tool as a replacement to Doxygen. It’s all still work
>> in progress, but it’s getting to the point where it will be actually
>> usable for projects. Compared to Doxygen, we’re trying to give some
>> significant improvements with regard to the output and control
>> thereof, as well as improve integration with build systems for
>> incremental builds and distribution. Of course this is all using
>> Clang behind the scenes. Within time, we will be open-sourcing it and
>> will definitely need some hands to keep the project going, as well as to, for example, extend Clang’s Doxygen parser.
>>
>>
>>
>> However, before we get to that point, we are concerned with something
>> slightly off topic: the name, of which the tool currently does not have one.
>> We had ClangDoc/clangdoc in mind, but we’re wondering about the
>> general consensus of naming Clang-based tooling after Clang itself?
>> Is there anything against that?
>>
>>
>>
>> Kind regards,
>>
>>
>>
>> Athos
>>
>>
>>
>> Junior Tools Programmer
>>
>> Guerrilla
>>
>>
>>
>>
>> _______________________________________________
>> cfe-dev mailing list
>> [hidden email]
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>>
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev



--
GCS a+ e++ d- C++ ULS$ L+$ !E- W++ P+++$ w++$ tv+ b++ DI D++ 5++ The Tao of math: The numbers you can count are not the real numbers.
Life is complex, with real and imaginary parts.
"Ok, it boots. Which means it must be bug-free and perfect. " -- Linus Torvalds "People disagree with me. I just ignore them." -- Linus Torvalds
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: A new clang-based documentation tool

Sumner, Brian via cfe-dev
In reply to this post by Sumner, Brian via cfe-dev
Hi Chenwj,

That's good to know, thanks! We'd rather refrain from using Doxygen in the name though, Doxygen replacement should be read as: we are currently using Doxygen, but we will be using this instead because.  It's quite a different thing altogether, the only similarities would be that we intend to parse the same style (at least).

We'll settle with clang-doc in that case.

- Athos

-----Original Message-----
From: 陳韋任 [mailto:[hidden email]]
Sent: Wednesday, August 2, 2017 11:46 PM
To: Athos van Kralingen <[hidden email]>
Cc: [hidden email]
Subject: Re: [cfe-dev] A new clang-based documentation tool

Hi Athos,

  My impression is we usually name the tool with dash in between, like clang-diff, clang-format, ... etc.
IMHO, clang-doxygen will be good as it remind me it tends to replace doxygen.

Regards,
chenwj

2017-08-01 17:27 GMT+08:00 Athos van Kralingen via cfe-dev
<[hidden email]>:

> Hi there,
>
>
>
> I’d like to let you know that we’re currently working on a
> documentation tool as a replacement to Doxygen. It’s all still work in
> progress, but it’s getting to the point where it will be actually
> usable for projects. Compared to Doxygen, we’re trying to give some
> significant improvements with regard to the output and control
> thereof, as well as improve integration with build systems for
> incremental builds and distribution. Of course this is all using Clang
> behind the scenes. Within time, we will be open-sourcing it and will
> definitely need some hands to keep the project going, as well as to, for example, extend Clang’s Doxygen parser.
>
>
>
> However, before we get to that point, we are concerned with something
> slightly off topic: the name, of which the tool currently does not have one.
> We had ClangDoc/clangdoc in mind, but we’re wondering about the
> general consensus of naming Clang-based tooling after Clang itself? Is
> there anything against that?
>
>
>
> Kind regards,
>
>
>
> Athos
>
>
>
> Junior Tools Programmer
>
> Guerrilla
>
>
>
>
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>



--
Wei-Ren Chen (陳韋任)
Homepage: https://people.cs.nctu.edu.tw/~chenwj
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: A new clang-based documentation tool

Sumner, Brian via cfe-dev
In reply to this post by Sumner, Brian via cfe-dev

As the developers of DoxyPress we have become extremely familiar with
the code base we inherited from Doxygen two years ago. There is an
option in Doxygen for clang assisted parsing using libClang, not
libTooling.  It is not using clang as the primary parser for C++.  The
maintainer uses libClang in conjunction with the lex only parser to
process the names of templates when the lex parser reaches an invalid
state.

DoxyPress was refactored over a year ago to use a combination of
libClang to extract comments and libTooling for full C++ parsing.
Neither library was sufficient on its own.  We have worked with many
companies who were unable to parse C++ code with Doxygen who can now use
DoxyPress seamlessly.

As a great test we have generated docs for clang itself with a better
html output than current Doxygen output.  Doxygen was a great product at
one time but each time C++ changes the maintainer has to add new lex
rules by hand to the parser.  Cool part about using clang is we get
support for the new standard with very little effort.


Barbara
Co-Founder of CopperSpice and DoxyPress



On 8/2/2017 11:37 PM, Csaba Raduly via cfe-dev wrote:
> There's also Doxygen, which can also use clang libraries for parsing :)
>




---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus

_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: A new clang-based documentation tool

Sumner, Brian via cfe-dev
In reply to this post by Sumner, Brian via cfe-dev
Athos,

A few minor points if I may. To be a replacement for Doxygen you would
need to support C++ as well as other languages such as C, C#,
JavaScript, Fortran, PHP, Python, etc.  You will also need to support
multiple outputs like HTML, CHM, RTF, Latex, QDoc, Docbook, etc.  You
will need to offer multiple types of diagrams, markdown syntax, and a
plethora of configuration options. If your new product does all this
that is wonderful.

DoxyPress is indeed a fork of Doxygen which is both a blessing and a
curse. In the two plus years we have worked on DoxyPress the changes
have been more than substantial.  To dismiss a product simply because it
is a fork misses the point.  We greatly value the work which has been
done on Doxygen.

DoxyPress is however a fundamentally different product from Doxygen. The
internals of our application have diverged from the original product. We
use modern C++,  value based instead of pointer based container classes,
smart pointers for memory management, and a slew of other
modifications.  It is faster and able to document languages and provide
output which Doxygen has issues with.

The basic idea I wanted to bring up is that DoxyPress is very different
internally and will continue to improve as our team has been growing and
by all indications will continue to do so.


Barbara




> Thanks for the heads up, but we were aware of those options and how far we could get with Doxygen itself. It being clang-based was not really the motivation behind the project; we just started fresh and Clang was by far the best option as a parser, hence we didn't simply opt for Doxygen or a modification thereof. The same goes for DoxyPress of course, as it is a fork of Doxygen, making it not much different.
>
> Our tool is a Doxygen replacement to us (and perhaps others eventually), but it is definitely very different in aspects such as output, configuration and with that, customization. We simply refer to Doxygen due to its seemingly dominant presence for creating c++ documentation.
>
> Also, if all goes well, it should also be more feasible to integrate into build systems, which gives, especially us, some options for scaling more easily too. A not unwelcome addition I'd say. There's some things left to do before that, though, but we'll make sure to keep this up to date as development progresses.
>
> - Athos
>




---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus

_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Loading...