doxygen-users

[Doxygen-users] Multiple executables with identical symbols?

[Hans <hgu...@xs...>]

Hi,


I have a largish project, consisting of 12 libraries and 50 or so 
executables. Some of the executables declare 'duplicate' class names - 
they are not real duplicates, of course, since they are never linked 
together, but the same name is still find in several places. How do I 
tell Doxygen that symbols from two executables really refer to two 
different things?

For example, foo.exe contains class MainWindow. bar.exe also contains 
class MainWindow, but of course it is a different thing altogether. Can 
I somehow get Doxygen to keep them separate in the output?

I don't want to run Doxygen 50 times, once for each executable. It would 
be incredibly slow, and take up a huge amount of diskspace.


Thanks in advance!

H. Guijt

Re: [Doxygen-users] Multiple executables with identical symbols?

[Richard D. <Ri...@Da...>]

On 1/19/19 10:03 AM, Hans wrote:
> Hi,
>
>
> I have a largish project, consisting of 12 libraries and 50 or so
> executables. Some of the executables declare 'duplicate' class names -
> they are not real duplicates, of course, since they are never linked
> together, but the same name is still find in several places. How do I
> tell Doxygen that symbols from two executables really refer to two
> different things?
>
> For example, foo.exe contains class MainWindow. bar.exe also contains
> class MainWindow, but of course it is a different thing altogether.
> Can I somehow get Doxygen to keep them separate in the output?
>
> I don't want to run Doxygen 50 times, once for each executable. It
> would be incredibly slow, and take up a huge amount of diskspace.
>
>
> Thanks in advance!
>
> H. Guijt
>
That isn't really how Doxygen is intended to be used from what I know,
but one way around it would be for each executable to place its
duplicates in a unique namespace (perhaps named for the executable), and
then Doxygen would document each in its own namespace, and not see them
as duplicates. The header declaring the class could even than bring the
name into the global namespace so most of the program doesn't need to
see the difference.

-- 
Richard Damon

Re: [Doxygen-users] Multiple executables with identical symbols?

[Robert H. <he...@de...>]

At Sat, 19 Jan 2019 12:24:33 -0500 Richard Damon <Ri...@Da...> wrote:

> 
> On 1/19/19 10:03 AM, Hans wrote:
> > Hi,
> >
> >
> > I have a largish project, consisting of 12 libraries and 50 or so
> > executables. Some of the executables declare 'duplicate' class names -
> > they are not real duplicates, of course, since they are never linked
> > together, but the same name is still find in several places. How do I
> > tell Doxygen that symbols from two executables really refer to two
> > different things?
> >
> > For example, foo.exe contains class MainWindow. bar.exe also contains
> > class MainWindow, but of course it is a different thing altogether.
> > Can I somehow get Doxygen to keep them separate in the output?
> >
> > I don't want to run Doxygen 50 times, once for each executable. It
> > would be incredibly slow, and take up a huge amount of diskspace.
> >
> >
> > Thanks in advance!
> >
> > H. Guijt
> >
> That isn't really how Doxygen is intended to be used from what I know,
> but one way around it would be for each executable to place its
> duplicates in a unique namespace (perhaps named for the executable), and
> then Doxygen would document each in its own namespace, and not see them
> as duplicates. The header declaring the class could even than bring the
> name into the global namespace so most of the program doesn't need to
> see the difference.

I'm presuming these classes are not actually in a public API library -- either
they are defined in "private" header files (header files only ever included in
the corresponding to the C++ main for the exe in question) or defined directly
in the C++ files specific to the exe in question). It might also make sense to
NOT use "correct" Doxygen commentting -- include comments of course, but not
formatted in a way that Doxygen recognizes (eg replace /** with /*+, etc.) --
Doxygen won't pick them up and won't document them (and won't get confused or
create confusing documentation). Since they don't document a public API, there
is no harm. Or don't actually feed the "private" header files or C++ source
code to Doxygen (unless you are using the C++ main program to create man1 or
man8 pages, or something like that -- eg program usage docs).

As Richard says "That isn't really how Doxygen is intended to be used...", you
probably *don't* want to "document" a non-public API, which is what these
classes sound like what they are. Doxygen is meant to document *public* APIs
(programs, classes, functions, etc.) that will be called by programs written
by other people, who would then link with your library or run your main 
programs (your .exe files).

-- 
Robert Heller             -- 978-544-6933
Deepwoods Software        -- Custom Software Services
http://www.deepsoft.com/  -- Linux Administration Services
he...@de...       -- Webhosting Services
                                                                                                         

Re: [Doxygen-users] Multiple executables with identical symbols?

[Hans <hgu...@xs...>]

On 19/01/2019 19:29, Robert Heller wrote:
> I'm presuming these classes are not actually in a public API library -- either
> they are defined in "private" header files (header files only ever included in
> the corresponding to the C++ main for the exe in question) or defined directly
> in the C++ files specific to the exe in question). It might also make sense to
> NOT use "correct" Doxygen commentting -- include comments of course, but not
> formatted in a way that Doxygen recognizes (eg replace /** with /*+, etc.) --
> Doxygen won't pick them up and won't document them (and won't get confused or
> create confusing documentation). Since they don't document a public API, there
> is no harm. Or don't actually feed the "private" header files or C++ source
> code to Doxygen (unless you are using the C++ main program to create man1 or
> man8 pages, or something like that -- eg program usage docs).
> 
> As Richard says "That isn't really how Doxygen is intended to be used...", you
> probably *don't* want to "document" a non-public API, which is what these
> classes sound like what they are. Doxygen is meant to document *public* APIs
> (programs, classes, functions, etc.) that will be called by programs written
> by other people, who would then link with your library or run your main
> programs (your .exe files).

Well, an executable doesn't have a public API of course, it's a closed 
unit so it's all private. My goal here is overal project documentation. 
It is for new developers, allowing them to better understand the system.

Is that actually an unusual use for Doxygen? It seems perfect for doing 
something like this - well, apart from the issue under discussion...

Re: [Doxygen-users] Multiple executables with identical symbols?

[Richard D. <Ri...@Da...>]

On 1/19/19 1:39 PM, Hans wrote:
> On 19/01/2019 19:29, Robert Heller wrote:
>> I'm presuming these classes are not actually in a public API library
>> -- either
>> they are defined in "private" header files (header files only ever
>> included in
>> the corresponding to the C++ main for the exe in question) or defined
>> directly
>> in the C++ files specific to the exe in question). It might also make
>> sense to
>> NOT use "correct" Doxygen commentting -- include comments of course,
>> but not
>> formatted in a way that Doxygen recognizes (eg replace /** with /*+,
>> etc.) --
>> Doxygen won't pick them up and won't document them (and won't get
>> confused or
>> create confusing documentation). Since they don't document a public
>> API, there
>> is no harm. Or don't actually feed the "private" header files or C++
>> source
>> code to Doxygen (unless you are using the C++ main program to create
>> man1 or
>> man8 pages, or something like that -- eg program usage docs).
>>
>> As Richard says "That isn't really how Doxygen is intended to be
>> used...", you
>> probably *don't* want to "document" a non-public API, which is what
>> these
>> classes sound like what they are. Doxygen is meant to document
>> *public* APIs
>> (programs, classes, functions, etc.) that will be called by programs
>> written
>> by other people, who would then link with your library or run your main
>> programs (your .exe files).
>
> Well, an executable doesn't have a public API of course, it's a closed
> unit so it's all private. My goal here is overal project
> documentation. It is for new developers, allowing them to better
> understand the system.
>
> Is that actually an unusual use for Doxygen? It seems perfect for
> doing something like this - well, apart from the issue under
> discussion...
>
I will use Doxygen for more than just Public API, which is one reason it
has the option to document internal/private members.

If the executables are really independent, I might be tempted to run
separate reports for each, and perhaps have the common library as a
independent set.

If the executables are more interrelated, my suggestion to put the
various executables into namespaces so as to make them unique can make
sense.

-- 
Richard Damon

Re: [Doxygen-users] Multiple executables with identical symbols?

[Robert H. <he...@de...>]

At Sat, 19 Jan 2019 19:39:08 +0100 Hans <hgu...@xs...> wrote:

> 
> On 19/01/2019 19:29, Robert Heller wrote:
> > I'm presuming these classes are not actually in a public API library -- either
> > they are defined in "private" header files (header files only ever included in
> > the corresponding to the C++ main for the exe in question) or defined directly
> > in the C++ files specific to the exe in question). It might also make sense to
> > NOT use "correct" Doxygen commentting -- include comments of course, but not
> > formatted in a way that Doxygen recognizes (eg replace /** with /*+, etc.) --
> > Doxygen won't pick them up and won't document them (and won't get confused or
> > create confusing documentation). Since they don't document a public API, there
> > is no harm. Or don't actually feed the "private" header files or C++ source
> > code to Doxygen (unless you are using the C++ main program to create man1 or
> > man8 pages, or something like that -- eg program usage docs).
> > 
> > As Richard says "That isn't really how Doxygen is intended to be used...", you
> > probably *don't* want to "document" a non-public API, which is what these
> > classes sound like what they are. Doxygen is meant to document *public* APIs
> > (programs, classes, functions, etc.) that will be called by programs written
> > by other people, who would then link with your library or run your main
> > programs (your .exe files).
> 
> Well, an executable doesn't have a public API of course, it's a closed 
> unit so it's all private. My goal here is overal project documentation. 
> It is for new developers, allowing them to better understand the system.
> 
> Is that actually an unusual use for Doxygen? It seems perfect for doing 
> something like this - well, apart from the issue under discussion...

Normally, I use Doxygen three ways (and guess this would be typical):

1: Document a public library's API (classic use of Doxygen).  Create 
documentation for programmers who might be interested using the libraries in 
their own programs from the comments in the source code.

2: Create man1/man8 pages for utility and daemon programs (document things 
like command line arguments, files used, etc.  This helps end users to 
properly run these utility and daemon programs that are part of the project.

3: Write out-of-program user manuals (the source header files will contain
only Doxygen-style comments and no actual code) -- Doxygen is good here in
that it creates quality "hard copy" (printable PDF) by way of LaTeX AND
equally quality "help pages" (as HTML), from a common source. The two formats
are consistent with each other and cover both use cases -- eg those that like
to click on a Help button or menu and have the documentation on the screen
alongside the running program and those that want a paper manual to read. 

(In practice, 1 yields man3, PDF, and HTML, 2 yields man1/man8, and 3 yields 
HTML and PDF, and when creating a user manual for a complex project, the user 
manual uses sources for both 2 & 3 -- eg, the "man" pages for the utility and 
daemon programs end up in their own chapters or in the appendix.  Feel free to 
visit my Model RR System's source tree on GitHub at 
https://github.com/RobertPHeller/ModelRRSystem for a package where I do this.)

For what you are doing you either need to run Doxygen for each "program" 
separately, creating a separate self-contained document OR you need to put the 
"private" classes in program-specific name spaces.  *Actually* there are all 
sorts of good reasons to do that anyway.  When the classes, etc. are in 
program-specific name spaces Doxygen will properly consider them different and 
distinct from each other.

> 
> 
> 
> 
> 
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
> 
>                                                                                                            

-- 
Robert Heller             -- 978-544-6933
Deepwoods Software        -- Custom Software Services
http://www.deepsoft.com/  -- Linux Administration Services
he...@de...       -- Webhosting Services