Re: Google Season of Docs

From: pbristow_at_[hidden]
Date: 2020-04-22 12:55:13

+1 Doxygen Syntax comments are THE standard way of describing expected code
performance.

Doxygen now understands C++ (using the Clang compiler so it really does ).

What the parameters and template parameters do, what items are updated, what is
returned, and of course, what a function does.

(The magic of how and why may be an added bonus).

Authors/documenters have to write this by hand - not just feed the code into
Doxygen!  (which is the delusion that many suffer from).

Quickbook and other tools can process this info (because it has a known
standard-ish syntax) and display it nicely.

Paul

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Jeff Garland via
Boost
> Sent: 22 April 2020 12:36
> To: Boost Developers List <boost_at_[hidden]>
> Cc: Jeff Garland <azswdude_at_[hidden]>
> Subject: Re: [boost] Google Season of Docs
> 
> To the point on Doxygen -- sorry, but it is needed and used by some of us.
> I'm not saying we shouldn't do something that ignores that, but don't expect
it to
> go away.
> 
> On Wed, Apr 22, 2020 at 3:13 AM Cem Bassoy via Boost <boost_at_[hidden]>
> wrote:
> 
> > Am Mo., 20. Apr. 2020 um 22:38 Uhr schrieb Glen Fernandes via Boost <
> > boost_at_[hidden]>:
> >
> > > On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski
> > > <hans.dembinski_at_[hidden]
> > >
> > > wrote:
> > > > My main question: I generate my reference with doxygen in xml. The
> > > > xml
> > > code is then post-
> > > > processed using a Python script. The result is then integrated
> > > > into my
> > > Quickbook docs(*) I
> > > > quickly checked Jamfiles for the example libraries you mentioned,
> > > > and
> > > none of those seem to
> > > > have a doxygen-generated reference. How would I combine doxygen
> > > > and
> > > Asciidoc?
> > >
> > > [...]
> > >
> > > > (*) How much annoyed I am by the inability of doxygen to produce a
> > > proper reference for a
> > > > template-heavy lib like Boost.Histogram is another story, but I
> > > > really
> > > don't want to write the
> > > > reference by hand either and keep it in sync with code changes
> > manually.
> > >
> > > I don't have a solution for that, I'm afraid. As you've found, all
> > > of the above have reference documentation manually written. (I
> > > stopped using Doxygen even when Quickbook/Boostbook was involved,
> > > though so I never invested time in finding out how to make things
> > > work with
> > > Doxygen)
> > >
> >
> > Yes, I am in doubt if Doxygen documentation is really a necessity for
> > library users and developers.
> > After seeing asciidoc and the simple document generation, I would like
> > to go with asciidoc for Boost.ublas.
> > I think, using C++ concepts will also help to better read and
> > understand template code - maybe eliminating the necessity to document
> > on a reference level.
> > Thanks Glen.
> >
> > -------------
> >
> > I would like to know the number of potential mentors for Google Summer
> > of Docs <https://developers.google.com/season-of-docs>.
> > For an example, see GSoD-Project-VLC
> > <
> > https://developers.google.com/season-of-docs/docs/2019/participants/pr
> > oject-videolan
> > >
> >
> > Short summary of the *timeline*:
> > Organization deadline is *May 4*.
> > Technical writer exploration is between *May 11 and Jun 8* -
> > Interested technical writers discuss project ideas with mentoring
> > organizations Technical writing projects announcement* August 16,
> > 2020* Community bonding *August 17 - September 13* Doc development
> > *September 14, 2020 - November 30* Project finalization *November 30 -
> > December 5*
> >
> >
> > How many library contributors and maintainers would like to mentor
> > professional technical writer?
> >
> > +1 for Boost.uBlas.
> >
> >
> > P.S.
> > There is also the chance to apply for a long-running project.
> > Would that be helpful for Boost?
> >
> >
> >
> > >
> > > _______________________________________________
> > > Unsubscribe & other changes:
> > > http://lists.boost.org/mailman/listinfo.cgi/boost
> > >
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
> 
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost