Automatic documentation conversion from Doxygen


ROOT Version: 6.22/02
Platform: CentOS 7
Compiler: GCC 4.8


Dear ROOT developers,

Thank you for a great feature you implemented recently: Multi-Python PyROOT to
use Python 3 and 2 with a single installation annonced in
ROOT Version 6.22 Release Notes.

I want to ask you some questions about ROOT documentation mechanism with Python
and Jupyter.

R seems to be able to convert documentation from roxygen (source code) to
console and even Jupyter. For instance I tested this tutorial:
Writing an R package from scratch | Not So Standard Deviations. After documentation build and package installation the comments from my demo package myFunction_6916762.tar.gz (744 Bytes) was correctly printed in the console:

$ R

R version 3.6.1 (2019-07-05) -- "Action of the Toes"
Copyright (C) 2019 The R Foundation for Statistical Computing
Platform: x86_64-conda_cos6-linux-gnu (64-bit)
[...]
> ?myFunction::add

add                 package:myFunction                 R Documentation

Add together two numbers

Description:

    Testing add function documentation in bt_spn #20401.

Usage:

    add(x, y)

Arguments:

[...]

(END)

and Jupyter:

.

Does a similar mechanism exist in ROOT? A previous topic may indicate that this
wasn’t the case in May 2019: Python help function on ROOT class methods.
However I suppose ROOT may have new documentation features in recent releases.

Is Chapter: HTMLDoc an equivalent of R documentation mechanism?

It would be nice to have Doxygen documentation into Cling, Python and
Jupyter.

Best regards,

@couet Is this something you can comment on?

In ROOT we build the reference guide automatically with doxygen. The link you are pointing too (HTMLDoc) is the old User’s Guide we are now replacing by the online manual. The THtml class is now deprecated.

Thank your for your answer.

Sorry I should have looked at ROOT: THtml Class Reference before mentioning it.

Is it possible to fetch Doxygen comments and print them in Cling, Python and Jupyter (ROOT C++ and Python)?

For instance how to easily access to TCanvas::GetWindowTopX() documentation shown in ROOT: TCanvas Class Reference?

Returns current top x position of window on screen.

I used ROOT: TClass Class Reference but wasn’t able to print the comment, e.g.:

$ root
   ------------------------------------------------------------------
  | Welcome to ROOT 6.22/02                        https://root.cern |
  | (c) 1995-2020, The ROOT Team; conception: R. Brun, F. Rademakers |
  | Built for linuxx8664gcc on Aug 17 2020, 12:46:52                 |
  | From tags/v6-22-02@v6-22-02                                      |
  | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q'       |
   ------------------------------------------------------------------

root [0] auto canvas = TClass::GetClass("TCanvas")
(TClass *) @0x7ffd5f1ea8f0
root [1] canvas->GetMethodAllAny("GetWindowTopX")->GetPrototype()
(const char *) "Int_t TCanvas::GetWindowTopX()"
root [0] .help TCanvas::GetWindowTopX

I think the underlying question is: does/can cling know about doxygen comments for functions and classes, the same way as Python functions and classes store theirs in their __doc__ attribute? (because all ways to use ROOT interactively – ROOT prompt, jupyter notebooks and Python/PyROOT – ultimately rely on cling to call into the C++ code).

I’m pretty sure the answer is that cling, like the good C++ interpreter it is, completely ignores comments :sweat_smile: @Axel is that right?

cling does know about comments :slight_smile: But going from there to documentation means re-implementing doxygen in ROOT. That’s a BIG project… I think .help is a more reasonable path: it makes use of doxygen’s power, has a nicer presentation (though some prefer terminals), - and we have it already.

Thank you for your answers. I suppose the method ROOT: TObject Class Reference may suggest that ROOT can “understand” some comments as @Axel said.

.help metacommand is indeed powerful as mentionned in
.help metacommand extension and use with Python/Jupyter.

Then what about retrieving (local) Doxygen information into console?
Warning: Viewer discretion advised:

$ root
   ------------------------------------------------------------------
  | Welcome to ROOT 6.22/02                        https://root.cern |
  | (c) 1995-2020, The ROOT Team; conception: R. Brun, F. Rademakers |
  | Built for linuxx8664gcc on Aug 17 2020, 12:46:52                 |
  | From tags/v6-22-02@v6-22-02                                      |
  | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q'       |
   ------------------------------------------------------------------

root [0] gSystem->Exec("links file:///data/[...]/URANIE/20401/[...]/root/doxygen/master/classTCanvas.html#a2aa8e879505f21da08af0853abe640c2")
   Int_t TCanvas::GetWindowTopX (  )                                                                                                                                                     
                                                                                                                                                                                         
   Returns current top x position of window on screen.                                                                                                                                   
                                                                                                                                                                                         
   Definition at line 1186 of file TCanvas.cxx.

Then q to quit:

                                                                                                                                                                                         
   Reimplemented from TPad.                                          +---------------- Quitter ? -----------------+                                                                      
                                                                     |                                            |                                                                      
   Definition at line 165 of file TCanvas.h.                         |  Êtes-vous sûr de vouloir quitter Links ?  |                                                                      
                                                                     |                                            |                                                                      
   Size_t TCanvas::GetXsizeReal (  ) const inline                    |              [ Oui ]  [ Non ]              |                                                                      
                                                                     +--------------------------------------------+                                                                      
   Definition at line 157 of file TCanvas.h.                                                                          
(int) 0
root [1] .q

That would imply to have the full Doxygen manual installed locally on machine ? isn’t ?
And that would fly for simple helps like the example you showed. But try complex classes with huge help, full of plots like THistPainter…

…and we only have limited resources, so we need to really focus on what’s needed by the vast majority of our users. We did not have a lot of requests for doc in terminal (through we did have some!)

Given the current “polls” I don’t expect this to happen.

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.