Re: Doxygen output?

[Andrew Sutherland]

On Tue, Feb 21, 2017, at 04:42 PM, Andrew Sutherland wrote:
> A sketch first steps implementation would be:

I took a shot at this.  The pull request with details is at
https://github.com/bill-mccloskey/searchfox/pull/11 and hopefully
self-explanatory screenshots are here:
https://clicky.visophyte.org/examples/searchfox/20170227/static-field-decl-comments.png
https://clicky.visophyte.org/examples/searchfox/20170227/static-field-uses.png
https://clicky.visophyte.org/examples/searchfox/20170227/method-def-decl-comment.png

Andrew
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[Benoit Girard]

I find it a bit unfortunate that people link are removed since mozilla
loses a lot of valuable resources and small test cases. With that being
said I have a repo with the scripts I used to run doxygen. I think mstange
might be running it somewhere.

https://github.com/bgirard/doxygen-mozilla

It will clone a tree and run doxygen on a list of modules with their own
doxygen configuration. Last time I tried a year or so ago doxygen would
hang if I ran it on the top level tree.

On Wed, Feb 22, 2017 at 12:55 AM, Henri Sivonen 
wrote:

> On Tue, Feb 21, 2017 at 12:42 AM,   wrote:
> > My short (<2yr) experience of the code gave me the impression that only
> a small amount of it has proper doxygen comments.
> > We must be frequenting different circles; or I'm somehow blind to them.
> :-)
>
> I get to look at stuff like:
> /**
>  * Cause parser to parse input from given URL
>  * @updategess5/11/98
>  * @param   aURL is a descriptor for source document
>  * @param   aListener is a listener to forward notifications to
>  * @return  TRUE if all went well -- FALSE otherwise
>  */
>
> > Anyway, they're mainly useful when generated websites/documents are
> readily available, which it seems isn't the case (anymore).
>
> Right. I'm trying to assess how much effort I should put into writing
> Doxygen-formatted docs, and if we aren't really publishing Doxygen
> output, I feel like it's probably good to write /** ... */ in case we
> start using Doxygen again but probably not worthwhile to use the @
> tags.
>
> On Tue, Feb 21, 2017 at 10:13 PM, Bill McCloskey 
> wrote:
> > I've been thinking about how to integrate documentation into Searchfox.
> One
> > obvious thing is to allow it to display Markdown files and
> > reStructuredText. I wonder if it could do something useful with Doxygen
> > comments though? Is this something people would be interested in?
>
> I think integrating docs with Searchfox would be more useful than
> having unintegrated Doxygen output somewhere. Compared to just reading
> a .h with comments, I think a documentation view would be particularly
> useful for templates and headers with a lot of inline definitions as a
> means to let the reader focus on the interface and hide the
> implementation (including hiding whatever is in a namespace with the
> substring "detail" in the name of the namespace for templates).
> ___
> dev-platform mailing list
> dev-platform@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-platform
>
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[Henri Sivonen]

On Tue, Feb 21, 2017 at 12:42 AM,   wrote:
> My short (<2yr) experience of the code gave me the impression that only a 
> small amount of it has proper doxygen comments.
> We must be frequenting different circles; or I'm somehow blind to them. :-)

I get to look at stuff like:
/**
 * Cause parser to parse input from given URL
 * @updategess5/11/98
 * @param   aURL is a descriptor for source document
 * @param   aListener is a listener to forward notifications to
 * @return  TRUE if all went well -- FALSE otherwise
 */

> Anyway, they're mainly useful when generated websites/documents are readily 
> available, which it seems isn't the case (anymore).

Right. I'm trying to assess how much effort I should put into writing
Doxygen-formatted docs, and if we aren't really publishing Doxygen
output, I feel like it's probably good to write /** ... */ in case we
start using Doxygen again but probably not worthwhile to use the @
tags.

On Tue, Feb 21, 2017 at 10:13 PM, Bill McCloskey  wrote:
> I've been thinking about how to integrate documentation into Searchfox. One
> obvious thing is to allow it to display Markdown files and
> reStructuredText. I wonder if it could do something useful with Doxygen
> comments though? Is this something people would be interested in?

I think integrating docs with Searchfox would be more useful than
having unintegrated Doxygen output somewhere. Compared to just reading
a .h with comments, I think a documentation view would be particularly
useful for templates and headers with a lot of inline definitions as a
means to let the reader focus on the interface and hide the
implementation (including hiding whatever is in a namespace with the
substring "detail" in the name of the namespace for templates).
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[Eric Rahm]

I was just thinking about this as I probably wouldn't use the standard
doxygen output much, but can definitely see the usefulness when integrated
into our code indexers which I use quite often. Most useful to me would be:

   - @param doc when hovering over a param (in function, or when calling a
   function)
  - bonus points for annotating the type
  - @class doc when hovering over a class (fallback to base class would
   be nice)
   - @method doc when hovering over a function definition or call

Integrating IDL docs would be nice as well.

-e

On Tue, Feb 21, 2017 at 12:13 PM, Bill McCloskey 
wrote:

> I've been thinking about how to integrate documentation into Searchfox. One
> obvious thing is to allow it to display Markdown files and
> reStructuredText. I wonder if it could do something useful with Doxygen
> comments though? Is this something people would be interested in?
>
> On Tue, Feb 21, 2017 at 11:53 AM, Ted Mielczarek 
> wrote:
>
> > We have auto-generated docs using Sphinx on ReadTheDocs[1]. If someone
> > was motivated, it looks like there does exist code[2] to bridge doxygen
> > docs into Sphinx, so it should be possible to get those docs into the
> > existing RTD setup. There are even docs on RTD[3] for how to add new
> > docs!
> >
> > -Ted
> >
> > 1. http://gecko.readthedocs.io/en/latest/
> > 2. https://breathe.readthedocs.io/en/latest/
> > 3. http://gecko.readthedocs.io/en/latest/#adding-documentation
> >
> >
> > On Mon, Feb 20, 2017, at 11:38 AM, Milan Sreckovic wrote:
> > > Not being kept up to date as far as I know.  My extraction is four
> years
> > > out of date (e.g.,
> > > https://people-mozilla.org/~msreckovic/Extracted/
> > MozillaCentral/html/annotated.html)
> > > and as you noted, Benoit's page is no longer.
> > >
> > > The code used to create it is here:
> > > https://github.com/bgirard/doxygen-mozilla
> > >
> > >
> > > On 20-Feb-17 2:05, Henri Sivonen wrote:
> > > > Our comments mostly try to follow the Doxygen format, and MDN says
> > > > that the documentation team has a tool for importing
> Doxygen-formatted
> > > > IDL comments into MDN articles.
> > > >
> > > > Other than that, is Doxygen output from m-c input being published
> > anywhere?
> > > >
> > > > https://people-mozilla.org/~bgirard/doxygen/gfx/ is 404 these days.
> > > >
> > >
> > > --
> > > - Milan (mi...@mozilla.com)
> > >
> > > ___
> > > dev-platform mailing list
> > > dev-platform@lists.mozilla.org
> > > https://lists.mozilla.org/listinfo/dev-platform
> > ___
> > dev-platform mailing list
> > dev-platform@lists.mozilla.org
> > https://lists.mozilla.org/listinfo/dev-platform
> >
> ___
> dev-platform mailing list
> dev-platform@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-platform
>
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[Andrew Sutherland]

On Tue, Feb 21, 2017, at 03:13 PM, Bill McCloskey wrote:
> I've been thinking about how to integrate documentation into Searchfox.
> One
> obvious thing is to allow it to display Markdown files and
> reStructuredText. I wonder if it could do something useful with Doxygen
> comments though? Is this something people would be interested in?

I think an amazing thing searchfox could do would be to make it easier
to find the useful documentation that exists.  Having joined the
platform team with a somewhat pessimistic guess at the amount of useful
documentation, I've been pleasantly surprised by what's available. 
However, it's not always easy to know where the documentation is for
code until you've spent a lot of time with it, especially with the
amount of plumbing code we have with IPC.  That arguably defeats some of
the benefit of the docs.

For example, when looking at a C++ method and trying to understand what
its purpose is/why it's doing something, there could be useful comments:
- Preceding the C++ definition or just inside the method.
- Preceding the C++ declaration.
- Preceding the .idl definition of the method.
- Preceding the webidl definition of the method.
- In the spec that gives us the webidl definition.
- Related to another method that's just a thin wrapper around the method
we're looking at.  (And which can be pierced by hints or following the
call-graph with heuristics like noticing the callee's name is within
some edit distance of the caller's name and the caller does very little
else, or that the caller just seems to set up a runnable, etc.)
- Referenced by in-tree overview markdown docs like devtools has in
http://searchfox.org/mozilla-central/source/devtools/docs
- Referenced by in-tree overview pandoc docs like SpiderMonkey has in
http://searchfox.org/mozilla-central/source/js/src/doc (and which are
reflected to MDN)
- Referenced by in-tree sphinx-friendly docs that are reflected to
https://gecko.readthedocs.io/en/latest/
- Referenced/documented by something on wiki.mozilla.org
- Referenced/documented by something on developer.mozilla.org (ignoring)

A sketch first steps implementation would be:
- Have the file indexers use heuristics to detect block comments and
associate them with the following definition/declaration.  (Maybe the
clang AST already does this?)  No need to try and parse the doxygen at
first, just be able to display it in a human-readable fashion.  Log the
comment plus its kind (decl, def, idl, etc.).  Well, maybe bless a few
things like @see/@sa or @related to allow explicit doc-references to
other identifiers to exist.
- Aggregate a "docs" file similar to "crossrefs" that stores
per-identifier doc links and excerpts.
- Do not bake the comments into the syntax-highlighted source to avoid
combinatorial explosion.
- Have router.py expose an API to lookup the documentation associated
with one or more identifiers, possibly following inheritance (when
implemented in searchfox) and override relationships as appropriate.
- Have hovering over a symbol prefetch/cache the docs for a symbol.
- Transform the menu displayed when clicking on a symbol to a mega menu
(a la
http://bjk5.com/post/44698559168/breaking-down-amazons-mega-dropdown). 
Have a top-level entry displaying hints about what docs are available,
like "Docs (h idl webidl...)" or greyed out "No Docs".  Have the
expanded submenu be the excerpts displayed right there so they can be
read in their entirety if they're terse.  The goal is that the user
doesn't need to click through to a full docs search or to follow the
links to the docs to read them unless they want to.  This idiom could
also be used for inheritance information and overrides.

Andrew
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[Bill McCloskey]

I've been thinking about how to integrate documentation into Searchfox. One
obvious thing is to allow it to display Markdown files and
reStructuredText. I wonder if it could do something useful with Doxygen
comments though? Is this something people would be interested in?

On Tue, Feb 21, 2017 at 11:53 AM, Ted Mielczarek  wrote:

> We have auto-generated docs using Sphinx on ReadTheDocs[1]. If someone
> was motivated, it looks like there does exist code[2] to bridge doxygen
> docs into Sphinx, so it should be possible to get those docs into the
> existing RTD setup. There are even docs on RTD[3] for how to add new
> docs!
>
> -Ted
>
> 1. http://gecko.readthedocs.io/en/latest/
> 2. https://breathe.readthedocs.io/en/latest/
> 3. http://gecko.readthedocs.io/en/latest/#adding-documentation
>
>
> On Mon, Feb 20, 2017, at 11:38 AM, Milan Sreckovic wrote:
> > Not being kept up to date as far as I know.  My extraction is four years
> > out of date (e.g.,
> > https://people-mozilla.org/~msreckovic/Extracted/
> MozillaCentral/html/annotated.html)
> > and as you noted, Benoit's page is no longer.
> >
> > The code used to create it is here:
> > https://github.com/bgirard/doxygen-mozilla
> >
> >
> > On 20-Feb-17 2:05, Henri Sivonen wrote:
> > > Our comments mostly try to follow the Doxygen format, and MDN says
> > > that the documentation team has a tool for importing Doxygen-formatted
> > > IDL comments into MDN articles.
> > >
> > > Other than that, is Doxygen output from m-c input being published
> anywhere?
> > >
> > > https://people-mozilla.org/~bgirard/doxygen/gfx/ is 404 these days.
> > >
> >
> > --
> > - Milan (mi...@mozilla.com)
> >
> > ___
> > dev-platform mailing list
> > dev-platform@lists.mozilla.org
> > https://lists.mozilla.org/listinfo/dev-platform
> ___
> dev-platform mailing list
> dev-platform@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-platform
>
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[Ted Mielczarek]

We have auto-generated docs using Sphinx on ReadTheDocs[1]. If someone
was motivated, it looks like there does exist code[2] to bridge doxygen
docs into Sphinx, so it should be possible to get those docs into the
existing RTD setup. There are even docs on RTD[3] for how to add new
docs!

-Ted

1. http://gecko.readthedocs.io/en/latest/
2. https://breathe.readthedocs.io/en/latest/
3. http://gecko.readthedocs.io/en/latest/#adding-documentation


On Mon, Feb 20, 2017, at 11:38 AM, Milan Sreckovic wrote:
> Not being kept up to date as far as I know.  My extraction is four years 
> out of date (e.g., 
> https://people-mozilla.org/~msreckovic/Extracted/MozillaCentral/html/annotated.html)
>  
> and as you noted, Benoit's page is no longer.
> 
> The code used to create it is here: 
> https://github.com/bgirard/doxygen-mozilla
> 
> 
> On 20-Feb-17 2:05, Henri Sivonen wrote:
> > Our comments mostly try to follow the Doxygen format, and MDN says
> > that the documentation team has a tool for importing Doxygen-formatted
> > IDL comments into MDN articles.
> >
> > Other than that, is Doxygen output from m-c input being published anywhere?
> >
> > https://people-mozilla.org/~bgirard/doxygen/gfx/ is 404 these days.
> >
> 
> -- 
> - Milan (mi...@mozilla.com)
> 
> ___
> dev-platform mailing list
> dev-platform@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-platform
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[gsquelart]

My short (<2yr) experience of the code gave me the impression that only a small 
amount of it has proper doxygen comments.
We must be frequenting different circles; or I'm somehow blind to them. :-)

Anyway, they're mainly useful when generated websites/documents are readily 
available, which it seems isn't the case (anymore). So I'm guessing people 
don't care to write/maintain them, because there is no obvious benefit at the 
moment.

I personally would welcome a push to make doxygen more official, at the very 
least for headers that get used between modules, but the more the better; and 
to have an official (or de-facto) generated website.

--
Gerald

On Monday, February 20, 2017 at 6:06:40 PM UTC+11, Henri Sivonen wrote:
> Our comments mostly try to follow the Doxygen format, and MDN says
> that the documentation team has a tool for importing Doxygen-formatted
> IDL comments into MDN articles.
> 
> Other than that, is Doxygen output from m-c input being published anywhere?
> 
> https://people-mozilla.org/~bgirard/doxygen/gfx/ is 404 these days.
> 
> -- 
> Henri Sivonen
> hsiv...@hsivonen.fi
> https://hsivonen.fi/
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

Re: Doxygen output?

[Milan Sreckovic]

Not being kept up to date as far as I know.  My extraction is four years 
out of date (e.g., 
https://people-mozilla.org/~msreckovic/Extracted/MozillaCentral/html/annotated.html) 
and as you noted, Benoit's page is no longer.


The code used to create it is here: 
https://github.com/bgirard/doxygen-mozilla



On 20-Feb-17 2:05, Henri Sivonen wrote:

Our comments mostly try to follow the Doxygen format, and MDN says
that the documentation team has a tool for importing Doxygen-formatted
IDL comments into MDN articles.

Other than that, is Doxygen output from m-c input being published anywhere?

https://people-mozilla.org/~bgirard/doxygen/gfx/ is 404 these days.



--
- Milan (mi...@mozilla.com)

___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform