Re: Doxygen

[Stephan Bergmann]

On 30/04/2020 03:34, Olivier Hallot wrote:

The way information is presented to the non-developer is sub-optimal.
Pre-Doxygen sdk was much easier to navigate and get information as the
ues cases below


What exactly do you mean with "pre-Doxygen sdk"?  (IIRC, Doxygen has 
been introduced to replace OOo's autodoc first for generation of the C++ 
API documentation and then for generation of the UNOIDL API documentation.)



With installed sdk in his computer at
file:///opt/libreoffice6.4/sdk/index.html


What exactly is installed there? 
 
or 
 
as currently available at ?



Let's suppose I am a candidate to macro programming and want to

Use case 1 : Search for ThisComponent -> no matches


Search how?  I find no ability to search on 
.  (Did you mean the search 
field at the top right of 
, reached from 
 via "IDL Reference"?  But 
then, "ThisComponent" is not a term related to LO's UNOIDL API, so no 
matches is a plausible outcome there.)


___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen

[Regis Perdreau]

Yes i confirm there are some lacks in doxygen. I'm not able to generate
myself documentation.  It will be interesting to generate uml diagram.
The doxygen process never ends on my computer.  I'm trying to test
Sourcetrails which is recently opensourced. It looks better for me. My goal
would be to able to recognize easily design pattern, inheritance and where
add méthods  without pain. For occasionnal self taught developper, it's
tricky to have global view of classes without a tool.

Regards,

Régis.








Le jeu. 30 avr. 2020 à 03:35, Olivier Hallot 
a écrit :

> Hi Michael
>
> Em 29/04/2020 13:39, Michael Stahl escreveu:
> > hi Olivier,
> >
> (snip)
>
> >
> > so you are unhappy with the current state? what in particular don't you
> > like about the API documentation?
>
> The way information is presented to the non-developer is sub-optimal.
> Pre-Doxygen sdk was much easier to navigate and get information as the
> ues cases below
>
> With installed sdk in his computer at
> file:///opt/libreoffice6.4/sdk/index.html
>
> Let's suppose I am a candidate to macro programming and want to
>
> Use case 1 : Search for ThisComponent -> no matches
>
> Use Case 2 : What are the methods/properties under getSheets() ?
> Answer : search for getSheets returns
>
> file:///opt/libreoffice6.4/sdk/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sheet_1_1XSpreadsheetDocument.html#a3ea7cfcc41c4d4690228e62ca4a6a55d
>
> where it says
> Public Member Functions
> com::sun::star::sheet::XSpreadsheetsgetSheets ()
> returns the collection of sheets in the document. More...
>
> NO mention to methods and properties of the collection object.
>
> just 2 examples on how hard it is to get information currently.
>
> I remind that if this sdk/documentation should be improved, we can look
> to get a resource funded by Google, provided we format into a tech doc
> project.
>
> Kind regards
> --
> Olivier Hallot
> LibreOffice Documentation Coordinator
> Comunidade LibreOffice
> Rio de Janeiro - Brasil - Local Time: UTC-03:00
> http://tdf.io/joinus
> ___
> LibreOffice mailing list
> LibreOffice@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/libreoffice
>
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen

[Olivier Hallot]

Hi Michael

Em 29/04/2020 13:39, Michael Stahl escreveu:
> hi Olivier,
> 
(snip)

> 
> so you are unhappy with the current state? what in particular don't you
> like about the API documentation?

The way information is presented to the non-developer is sub-optimal.
Pre-Doxygen sdk was much easier to navigate and get information as the
ues cases below

With installed sdk in his computer at
file:///opt/libreoffice6.4/sdk/index.html

Let's suppose I am a candidate to macro programming and want to

Use case 1 : Search for ThisComponent -> no matches

Use Case 2 : What are the methods/properties under getSheets() ?
Answer : search for getSheets returns
file:///opt/libreoffice6.4/sdk/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sheet_1_1XSpreadsheetDocument.html#a3ea7cfcc41c4d4690228e62ca4a6a55d

where it says
Public Member Functions
com::sun::star::sheet::XSpreadsheetsgetSheets ()
returns the collection of sheets in the document. More...

NO mention to methods and properties of the collection object.

just 2 examples on how hard it is to get information currently.

I remind that if this sdk/documentation should be improved, we can look
to get a resource funded by Google, provided we format into a tech doc
project.

Kind regards
-- 
Olivier Hallot
LibreOffice Documentation Coordinator
Comunidade LibreOffice
Rio de Janeiro - Brasil - Local Time: UTC-03:00
http://tdf.io/joinus
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen

[Michael Stahl]

hi Olivier,

On 29.04.20 17:29, Olivier Hallot wrote:

Hi fellow developers

Google Season of Doc is an opportunity to leverage documentation at
large. At the moment I am concerned in the effectiveness of the tool
Doxygen (which I know almost nothing) for code documentation and
especially for documenting the API, under the end-user perspective.

So far I can tell, as ocasional macro coder, that the API website is
(expletive deleted) and ineffective.


so you are unhappy with the current state? what in particular don't you 
like about the API documentation?



So I'd like to leverage the Google opportunity for documenting the API
in an usable, searchable and truly effective for macro coders.

Please drop me a note on how can I build a case for Google that will
benefit all of us. I can be mentor but I need guidelines from
experienced devs.


unfortunately i don't know how to advise you how to best argue for 
fixing unspecific and unidentified problems :)

___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen

[William Gathoye (LibreOffice)]

Hum. It could be case. [1]

If this is really open to all LibO contributors[2] and the stipend is
confirmed, I find this program interesting =)

[1] https://developers.google.com/season-of-docs/docs/tech-writer-stipends
[2] Me?

-- 
William Gathoye
Hypertive volunteer for LibreOffice
Proud member of The Document Foundation
Member of LaMouette - French based association promoting ODF and LibreOffice
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen

[William Gathoye (LibreOffice)]

Hi Olivier,

On 29/04/2020 17:29, Olivier Hallot wrote:

> So I'd like to leverage the Google opportunity for documenting the API
> in an usable, searchable and truly effective for macro coders.

Is the Google Season of Doc a paid job? I mean like GSoC do persons
contributing get paid a stipend?


Hypertive volunteer for LibreOffice
Proud member of The Document Foundation
Member of LaMouette - French based association promoting ODF and LibreOffice
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: doxygen: Illegal command n as part of a title section

[vl01]

Hello,

On 4/5/19 2:50 AM, himajin10 wrote:


http://www.doxygen.nl/manual/commands.html#cmdpar

says title follows @par command. Probably that par title does not accept 
@n is the cause of the warning.


Does anyone know the the correct syntax? I still haven't search for it.


The syntax is correct, but since version 1.8.14 doxygen has that 
problem. See the filed bug report 
https://github.com/doxygen/doxygen/issues/6304


Cheers,

 Jens
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: doxygen: Illegal command n as part of a title section

[Alexander Thurgood]

Le 05/04/2019 à 11:50, himajin10 a écrit :

Hi,

> Hello, himajin10 here!
> 
> When I build LibreOffice locally, I often get just a bit upset because
> of the following warnings. Less warning will give me less stress :-)
> 

FWIW, I also see these when building on macOS, but have never gotten
around to checking whether it causes an issue in the API documentation.

Alex


___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: doxygen: Illegal command n as part of a title section

[himajin100000]

self-reminder

* DocTitle
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L4596
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L4539
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L4547
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L1387

* DocPara
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L4601
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L6593
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L6749
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L6787
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L5489
https://github.com/doxygen/doxygen/blob/208c689e4c13cc065045a6f6b1ff685eda5a3cd6/src/docparser.cpp#L5816
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen output on docs.libreoffice.org

[Miklos Vajna]

On Fri, Jan 08, 2016 at 09:31:24AM +1100, Chris Sherlock 
 wrote:
> Oh, and further to this - it appears that OpenGrok is updated once a day… is 
> it possible to do this more frequently? I find OpenGrok to be a great way of 
> exploring the codebase. There’s something ridiculously intuitive about the 
> way it presents things, at least to me. 

Even if it's updated more frequently, it'll never show your local
changes. :-)

'make id' / 'make tags' can do that, and it's up to you how often you
run them, perhaps give them a try.

There are detailed notes at
 for the
tags/vim combo.


signature.asc
Description: Digital signature
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen output on docs.libreoffice.org

[Chris Sherlock]

Nice - I’ll do just that :-)

I’ve got one more patch and then Doxygen will index the VCL module cleanly with 
no warnings, which was a major pain to do but I thought it was worth it. 

I’m running that on my own system now, I’ll check out the ctags/vim combo. 

Chris

> On 8 Jan 2016, at 8:27 PM, Miklos Vajna  wrote:
> 
> On Fri, Jan 08, 2016 at 09:31:24AM +1100, Chris Sherlock 
>  wrote:
>> Oh, and further to this - it appears that OpenGrok is updated once a day… is 
>> it possible to do this more frequently? I find OpenGrok to be a great way of 
>> exploring the codebase. There’s something ridiculously intuitive about the 
>> way it presents things, at least to me. 
> 
> Even if it's updated more frequently, it'll never show your local
> changes. :-)
> 
> 'make id' / 'make tags' can do that, and it's up to you how often you
> run them, perhaps give them a try.
> 
> There are detailed notes at
>  for the
> tags/vim combo.
> ___
> LibreOffice mailing list
> LibreOffice@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/libreoffice

___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Doxygen output on docs.libreoffice.org

[Chris Sherlock]

Oh, and further to this - it appears that OpenGrok is updated once a day… is it 
possible to do this more frequently? I find OpenGrok to be a great way of 
exploring the codebase. There’s something ridiculously intuitive about the way 
it presents things, at least to me. 

Chris

> On 8 Jan 2016, at 8:51 AM, Chris Sherlock  wrote:
> 
> Hi all, 
> 
> The Doxygen documentation on docs.libreoffice.org doesn’t appear to be 
> keeping up with the code… can someone tell me how often this is updated… and 
> perhaps why it doesn’t stay in sync with master?
> 
> Thanks!
> Chris Sherlock

___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: doxygen warning / nested comments

[Stephan Bergmann]

On 06/18/2014 05:16 PM, Lionel Elie Mamane wrote:

Noticed in my build:

/home/master/src/libreoffice/workdirs/libreoffice-4-3/udkapi/com/sun/star/io/FilePermission.idl:76:warning:
 Reached end of file while still inside a (nested) comment. Nesting level 1 
(probable line reference: 25)

This seems to be a message from doxygen. This looks like the
documentation of FilePermission will be blank because the content is
skipped because taken as part of comment... However,
http://api.libreoffice.org/docs/idl/ref/structcom_1_1sun_1_1star_1_1io_1_1FilePermission.html
looks reasonable, so maybe this is a red herring.


No idea with exactly what 4.2 sources and what toolchain 
http://api.libreoffice.org/docs/idl/ref has been generated, but at 
least recent Doxygen 1.8.6 and 1.8.7 indeed would miss documentation of 
FilePermissions.


Looks like Doxygen deliberately tracks nested /* ... */ comments within 
/** ... */ comments (cf. g_nestingCount in src/commentcnv.l), maybe to 
support such comments inside @code blocks as discussed at 
https://sourceforge.net/p/doxygen/mailman/doxygen-users/thread/ad6e09750605081949w8555322u711dbb4eb8dc0...@mail.gmail.com/ 
[Doxygen-users] how to add c-style comments inside @code?  But I did 
not find any rationale for that in the Doxygen documentation at 
http://www.stack.nl/~dimitri/doxygen/manual/index.html.


Anyway, worked around now on master and libreoffice-4-3, so future 
updates of http://api.libreoffice.org/docs/idl/ref should also be safe.


Stephan
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: doxygen API doc: list of uses?

[Michael Stahl]

On 10/09/13 15:55, Lionel Elie Mamane wrote:
 On Wed, Sep 04, 2013 at 11:56:07PM +0200, Andras Timar wrote:
 
 I updated api.libreoffice.org from master.
 
 We seem to have lost the feature of e.g.
  
 http://www.openoffice.org/api/docs/common/ref/com/sun/star/util/Date-xref.html
 that is the list of all the places in the API where this type is used.

well i though that stuff is more easily found with git grep anyway so
didn't bother to invest any time in that.

 The references in the Developer's guide of this section were
 interesting, too.

ah so that's where the REF: stuff in idl_chapter_refs.txt ends up!  i
always wondered but somehow managed to miss that.  currently only the
TOPIC: lines from idl_chapter_refs.txt are extracted via wikilinks.py;
it would be quite easy to extract the REF: lines too if you are interested.

 I don't find that feature in the Doxygen output. Is it just my
 blindness or have we voluntarily regressed here?

personally i think the inheritance graphs from Doxygen are a lot more
useful than the Uses pages from autodoc.


___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: doxygen API doc: list of uses?

[Lionel Elie Mamane]

On Wed, Sep 11, 2013 at 05:15:57PM +0200, Michael Stahl wrote:
 On 10/09/13 15:55, Lionel Elie Mamane wrote:
  On Wed, Sep 04, 2013 at 11:56:07PM +0200, Andras Timar wrote:
  
  I updated api.libreoffice.org from master.
  
  We seem to have lost the feature of e.g.
   
  http://www.openoffice.org/api/docs/common/ref/com/sun/star/util/Date-xref.html
  that is the list of all the places in the API where this type is used.
 
 well i though that stuff is more easily found with git grep anyway so
 didn't bother to invest any time in that.

git grep is not obvious / easy to use for that, and possibly not
completely possible to use. Case in point:

git grep com::sun::star::util::Date
# drats, also occurrences of shows com::sun::star::util::DateTime
git grep -E 'com::sun::star::util::Date[[:space:]]'
# drats, misses com/sun/star/util/DateTimeWithTimezone.idl
( git grep -E 'com::sun::star::util::Date[[:space:]]' offapi; \
  git grep -E 'sun::star::util::Date[[:space:]]' offapi/com; \
  git grep -E 'star::util::Date[[:space:]]' offapi/com/sun; \
  git grep -E 'util::Date[[:space:]]' offapi/com/sun/star; \
  git grep -E 'Date[[:space:]]' offapi/com/sun/star/util; \
) | $PAGER
# starts to be quite complicated... and lots to type...
# need to write a wrapper script that creates the right series
# of git grep...
# and gives duplicates... So something like
( git grep -E 'com::sun::star::util::Date[[:space:]]' offapi; \
  git grep -E 'sun::star::util::Date[[:space:]]' offapi/com; \
  git grep -E 'star::util::Date[[:space:]]' offapi/com/sun; \
  git grep -E 'util::Date[[:space:]]' offapi/com/sun/star; \
  git grep -E 'Date[[:space:]]' offapi/com/sun/star/util; \
) | sort -u | $PAGER


And still, this solution could still have false positives!
(although this particular example does not). E.g. imagine a
 com::sun::star::sdbc::util::Date, which is referred to in
 com/sun/star/sdbc/Foo.idl as:
 [property] util::Date Bar;
it would be matched by the
  git grep -E 'util::Date[[:space:]]' offapi/com/sun/star

And still, this solution still shows matches within comments in .idl
files (this example does not show any only because all matches are at
the end of a sentence and thus are followed by a fullstop and not
space). But e.g.
 git grep -E com::sun::star::util::XCloneable'[[:space:]]'
has *five* such false positives, for only *one* true positive. Bad
score.

So, no, really, IMHO git grep is not a proper substitute for
doxygen's true parsing, handling of such namespacing, comments, etc.


The doxygen graphs seem to be collapsed when they get too big... Not
sure I like that...

Compare

  
http://www.openoffice.org/api/docs/common/ref/com/sun/star/util/XCloneable-xref.html#SupportingServices
  
http://www.openoffice.org/api/docs/common/ref/com/sun/star/util/XCloneable-xref.html#Deriveds

and

  
http://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1util_1_1XCloneable.html

The first shows e.g.

::com::sun::star::report::XReportControlModel
::com::sun::star::report::XFixedLine
::com::sun::star::report::XFixedText
::com::sun::star::report::XFormattedField
::com::sun::star::report::XImageControl
::com::sun::star::report::XShape
::com::sun::star::report::XReportDefinition

  ::com::sun::star::awt::UnoControlNumericFieldModel
  ::com::sun::star::awt::UnoControlPatternFieldModel
  ::com::sun::star::awt::UnoControlProgressBarModel
  ::com::sun::star::awt::UnoControlRadioButtonModel
  ::com::sun::star::awt::UnoControlRoadmapModel
  ::com::sun::star::awt::UnoControlScrollBarModel

But these do not appear in the doxygen graph because it is cut at
their parent.

 I don't find that feature in the Doxygen output. Is it just my
 blindness or have we voluntarily regressed here?

 personally i think the inheritance graphs from Doxygen are a lot more
 useful than the Uses pages from autodoc.

The inheritance graphs are nice, and they give about the same
information as Derived Interfaces and Services which Support this
Interface sections, with a prettier layout and with the added bonus
that the Services which Support this Interface part is more
structured (shows inheritance path instead of flattening it out).

*But* they do not give _at_ _all_ the information from Uses as Return
Type, Uses as Parameter nor Uses as Data Type, where as explained
above, I don't see git grep as a good replacement.

-- 
Lionel
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice