Boost logo

Boost :

Subject: Re: [boost] ATTENTION: Library requirements..
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-01-07 09:23:46


> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Agustín K-ballo Bergé
> Sent: 07 January 2016 12:41
> To: boost_at_[hidden]
> Subject: Re: [boost] ATTENTION: Library requirements..
>
> On 1/7/2016 7:53 AM, Louis Dionne wrote:
> > Robert Ramey <ramey <at> rrsd.com> writes:
> >
> >>
> >> A few observations
> >>
> >> [...]
> >>
> >> f) javescript.
> >>
> >> I thing the admonitions agains java script should be softened. Most
> >> of the concerns existent when the document was originally written
> >> don't apply to day. I would like to see our html documentation
> >> support thinks like syntax coloring, running example code online, and
> >> the like. These things are often supported via injected javascript.
> >>
> >
> > +1
> >
> > I think JavaScript should be allowed, and even encouraged when it
> > makes the documentation much superior. For example, Hana uses
> > JavaScript to integrate performance benchmarks to the documentation in a nice way.
>
> I'm one of those that used to disable javascript by default. I wouldn't mind its use when it
results in a
> superior documentation, as long as it's optional and I can still get at least a mediocre
documentation
> with the basic information, and possibly some hint that I need to enable javascript for this site
to see
> more (not just to navigate differently).
>
> > Plus, all major browsers support JavaScript now, so I see this
> > restriction as being outdated.
>
> That might address one of the reasons given for banning it, namely:
>
> - Incompatible with some older browsers and some text based browsers.
>
> What's your take on the remaining ones?
>
> - Makes printing docs pages difficult.
> - Often results in really bad user interface design.
> - "It's just annoying in general."
> - Would require Boost to test web pages for ECMAScript/JavaScript compliance.
> - Makes docs maintenance by other than the original developer more difficult.

Isn't necessary?

Paul

PS In discussing documentation, we seem to be focussing only the 'printed page' documentation.

Perhaps we should be looking forward to providing more 'documentation' that appears when using an
IDE?

You get this already to some extent with Visual Studio when hovering over a function or parameter
name - the information about the function provided as a comment shows. This is much more helpful
than reams of C++ reference documentation.

To get this to work well, we need to have a *syntax* to the comments that could only show the
relevant information, or a choice perhaps. The existing defecto standard of Doxygen, like

\function a_function Does something Really Useful.
\param thingys How many thingys to do something with.

might serve this purpose.

(At present, if you have a big Doxygen comment, you get everything, perhaps more than you want).

Of course you still need tutorial-style examples with code snippets that will be web browsable.


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk