doxygen-users — List for users of doxygen

Re: [Doxygen-users] any way to suppress - prepending \brief to \details in class & file members ?

[Albert <alb...@gm...>]

Monique,

Did you have a look at e.g. BRIEF_MEMBER_DESC and REPEAT_BRIEF in the
Doxyfile ?

Albert

On Wed, Sep 16, 2015 at 2:55 AM, Monique Semp <mon...@ea...>
wrote:

> Hello, Doxygen users,
>
> I’m wondering if there’s any way to suppress the standard behavior of the
> \brief and \details commands for class & file members? As it says in the
> documentation,
> https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdbrief, the
> \brief is prepended to the \details.
>
> But I really, really wish that when there is a \details command, only it
> would appear in the output (without the prepended \brief content).
>
> Details:
>
> My problem (using Doxygen 1.8.10, but I don’t think the version is
> relevant) is that I’ve started a project to convert a huge amount of
> DoxyS-commented code to Doxygen comments, and DoxyS does not include the
> \brief content for members if there is also a \details section. And so way
> back when, when I created this body of DoxyS-commented code, I pretty much
> repeated the info from the \brief in the \details, but in a full-sentence
> format vs. the “phrase” format of the \brief.
>
> That is, for \brief I’d say, “Register a callback.” But for \details, I’d
> say, “This function registers a callback for component XYZ.”
>
> But now I’m porting everything (all ~150 files, with well more than a
> thousand functions/callbacks) to Doxygen. (I want to port it because DoxyS
> is not an active project; it has performance issues with groups; and it
> doesn’t support LaTeX, which I want to generate a good PDF.) And so the
> member descriptions look awful with the \brief prepended to the \details.
>
> It’s a pretty giant conversion project (lots of the tags are the same, but
> the text formats and autolinking are all different), but a lot is
> scriptable. But editing the \details to not repeat what’s in the \brief
> will require human interaction.
>
> Thanks for any ideas,
> -Monique
>
>
>
> ------------------------------------------------------------------------------
> Monitor Your Dynamic Infrastructure at Any Scale With Datadog!
> Get real-time metrics from all of your servers, apps and tools
> in one place.
> SourceForge users - Click here to start your Free Trial of Datadog now!
> http://pubads.g.doubleclick.net/gampad/clk?id=241902991&iu=/4140
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>

[Doxygen-users] any way to suppress - prepending \brief to \details in class & file members ?

[Monique S. <mon...@ea...>]

Hello, Doxygen users,

I’m wondering if there’s any way to suppress the standard behavior of the \brief and \details commands for class & file members? As it says in the documentation, https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdbrief, the \brief is prepended to the \details.

But I really, really wish that when there is a \details command, only it would appear in the output (without the prepended \brief content).

Details:

My problem (using Doxygen 1.8.10, but I don’t think the version is relevant) is that I’ve started a project to convert a huge amount of DoxyS-commented code to Doxygen comments, and DoxyS does not include the \brief content for members if there is also a \details section. And so way back when, when I created this body of DoxyS-commented code, I pretty much repeated the info from the \brief in the \details, but in a full-sentence format vs. the “phrase” format of the \brief.

That is, for \brief I’d say, “Register a callback.” But for \details, I’d say, “This function registers a callback for component XYZ.”

But now I’m porting everything (all ~150 files, with well more than a thousand functions/callbacks) to Doxygen. (I want to port it because DoxyS is not an active project; it has performance issues with groups; and it doesn’t support LaTeX, which I want to generate a good PDF.) And so the member descriptions look awful with the \brief prepended to the \details.

It’s a pretty giant conversion project (lots of the tags are the same, but the text formats and autolinking are all different), but a lot is scriptable. But editing the \details to not repeat what’s in the \brief will require human interaction.

Thanks for any ideas,
-Monique

Re: [Doxygen-users] FILTER_PATTERNS not working?

[Clayton <cla...@gm...>]

On Thu, 10 Sep 2015 20:37:31 +0800
Clayton <cla...@gm...> wrote:

> On Thu, 10 Sep 2015 13:31:33 +0200
> Dimitri van Heesch <do...@gm...> wrote:
> 
> > 
> > > On 10 Sep 2015, at 13:15 , Clayton <cla...@gm...> wrote:
> > > 
> > > Hi guys,
> > > 
> > > Take for instance this Visual Basic project:
> > > 
> > > 	https://github.com/mbedded-ninja/AltiumScriptCentral
> > > 
> > > and using this plugin filter:
> > > 
> > > 	https://github.com/sevoku/doxygen-vb-filter
> > > 
> > > In Doxyfile, if I put:
> > > 
> > > FILE_PATTERNS = *.vbs
> > > INPUT_FILTER = /path/to/plugins/visual_basic/vbfilter.sh
> > > FILTER_PATTERNS =
> > > 
> > > it works, I get output. However if I use these settings:
> > > 
> > > FILE_PATTERNS = *.vbs
> > > INPUT_FILTER = 
> > > FILTER_PATTERNS = *.vbs=/path/to/plugins/visual_basic/vbfilter.sh
> > > 
> > > nothing happens except a lot more warnings, whose meaning is not
> > > clear to me.
> > > 
> > > I have WARN_LOGFILE turned on, and attached are the warnings
> > > corresponding to the two scenarios.
> > > 
> > > So is something broken, or am I misconfigured? Opinions?
> > 
> > It helps to know which version of doxygen you are using and on which
> > platform/OS.
> 
> Sorry, my mistake: I am using a locally built version of doxygen
> 
> 	$ doxygen --version
> 	1.8.11
> 
> up-to-date with today's master branch, running on Debian Testing
> (Linux).
> 
> > Also check this:
> > http://doxygen.10944.n7.nabble.com/FILTER-PATTERNS-vs-INPUT-FILTER-td3873.html
> 
> I don't believe I see anything in there that is incompatible with what
> I am doing. I could have sworn I saw FILTER_PATTERNS work some weeks
> ago with a different javascript plugin, but maybe I was not looking
> straight. (I was new in these parts back then. I should probably
> retest.) Where do you figure those warnings in the error log come
> from, doxygen or the plugin?
> 
> Just seems odd though that it would work with INPUT_FILTER but not
> with FILTER_PATTERNS

I just retested the *.js scenario. With all else being the same, and the
latest master of doxygen:

These two scenarios 

	FILE_PATTERNS = *.js
	FILTER_PATTERNS = /path/to/plugins/js2doxy/js2doxy.pl

and

	FILE_PATTERNS = *.vbs
	INPUT_FILTER = /path/to/plugins/visual_basic/vbfilter.sh

work just fine and produce output. But this

	FILE_PATTERNS = *.vbs
	FILTER_PATTERNS = *.vbs=/path/to/plugins/visual_basic/vbfilter.sh

produces no output.

Clayton

Re: [Doxygen-users] browser support - for HTML output ?

[woody <kn...@re...>]

At 03:55 PM 9/8/2015 -0700, Monique Semp wrote:
> > Is there a list anywhere that says what the browser support is for Doxygen


It seems to be working o.k. under firefox 27.0.1 on windows

Re: [Doxygen-users] @internal effectively makes the function "undocumented" ?

[Monique S. <mon...@ea...>]

>From an off-list reply:

> Have you tried @private?   Doxygen seems very particular as to where the @private goes too.  If I put it in the comment block, I had
> problems.  Mine works ok like this:
> 

>    /**

>     * @brief Blah Blah Blah

>     * @param ae An Blah object.

>     */

>        void update(DDDTest ae)   /** @private */

>    {

>      …

>    }



Ah, I hadn’t thought of that! It does the job (I simply put the @private as the first thing in the Doxygen comment block), but it is extremely misleading to anyone who actually looks at the source code. (And this will happen because the Doxygen I’m working on is for internal use, not for customers. So the same developers who will use the Doxygen output will also be looking directly at the code.)



So what I did was create an alias, “dont_show”, for the @private command, and added a good explanation of it in the Doxyfile.



Thanks for the tip,

And hope this info and enhancement proves useful to others,

-Monique

[Doxygen-users] @internal effectively makes the function "undocumented" ?

[Monique S. <mon...@ea...>]

Hello, doxygen users,

I’m using Doxygen 1.8.10, on Win7.

I’ve just added the @internal command to some functions that I want to omit from the generated Doxygen output. However, they’re showing up in the list of functions, albeit without any of the Doxygen comments. I believe this is because I have the HIDE_UNDOC_MEMBERS set to NO, which I’m doing while I document the code so that it’s obvious if I’ve missed something. (I’m the tech writer who’s documenting an existing body of code; I’m not a developer documenting as I go.)

I’d have expected the @internal command to cause a function to be treated as “documented” but to omit it from the output because it’s internal. Clearly that’s not the case.

So, is there a way to achieve what I’m looking for: include undocumented elements (so I can see what I’ve missed adding comments for), but exclude elements that have the @internal designation?

If not, I’ll just set the HIDE_UNDOC_MEMBERS to YES and be careful as I go, so not a big deal.

Thanks,
-Monique

Re: [Doxygen-users] FILTER_PATTERNS not working?

[Clayton <cla...@gm...>]

On Thu, 10 Sep 2015 13:31:33 +0200
Dimitri van Heesch <do...@gm...> wrote:

> 
> > On 10 Sep 2015, at 13:15 , Clayton <cla...@gm...> wrote:
> > 
> > Hi guys,
> > 
> > Take for instance this Visual Basic project:
> > 
> > 	https://github.com/mbedded-ninja/AltiumScriptCentral
> > 
> > and using this plugin filter:
> > 
> > 	https://github.com/sevoku/doxygen-vb-filter
> > 
> > In Doxyfile, if I put:
> > 
> > FILE_PATTERNS = *.vbs
> > INPUT_FILTER = /path/to/plugins/visual_basic/vbfilter.sh
> > FILTER_PATTERNS =
> > 
> > it works, I get output. However if I use these settings:
> > 
> > FILE_PATTERNS = *.vbs
> > INPUT_FILTER = 
> > FILTER_PATTERNS = *.vbs=/path/to/plugins/visual_basic/vbfilter.sh
> > 
> > nothing happens except a lot more warnings, whose meaning is not
> > clear to me.
> > 
> > I have WARN_LOGFILE turned on, and attached are the warnings
> > corresponding to the two scenarios.
> > 
> > So is something broken, or am I misconfigured? Opinions?
> 
> It helps to know which version of doxygen you are using and on which
> platform/OS.

Sorry, my mistake: I am using a locally built version of doxygen

	$ doxygen --version
	1.8.11

up-to-date with today's master branch, running on Debian Testing
(Linux).

> Also check this:
> http://doxygen.10944.n7.nabble.com/FILTER-PATTERNS-vs-INPUT-FILTER-td3873.html

I don't believe I see anything in there that is incompatible with what
I am doing. I could have sworn I saw FILTER_PATTERNS work some weeks
ago with a different javascript plugin, but maybe I was not looking
straight. (I was new in these parts back then. I should probably
retest.) Where do you figure those warnings in the error log come from,
doxygen or the plugin?

Just seems odd though that it would work with INPUT_FILTER but not with
FILTER_PATTERNS	

Clayton

Re: [Doxygen-users] FILTER_PATTERNS not working?

[Dimitri v. H. <do...@gm...>]

> On 10 Sep 2015, at 13:15 , Clayton <cla...@gm...> wrote:
> 
> Hi guys,
> 
> Take for instance this Visual Basic project:
> 
> 	https://github.com/mbedded-ninja/AltiumScriptCentral
> 
> and using this plugin filter:
> 
> 	https://github.com/sevoku/doxygen-vb-filter
> 
> In Doxyfile, if I put:
> 
> FILE_PATTERNS = *.vbs
> INPUT_FILTER = /path/to/plugins/visual_basic/vbfilter.sh
> FILTER_PATTERNS =
> 
> it works, I get output. However if I use these settings:
> 
> FILE_PATTERNS = *.vbs
> INPUT_FILTER = 
> FILTER_PATTERNS = *.vbs=/path/to/plugins/visual_basic/vbfilter.sh
> 
> nothing happens except a lot more warnings, whose meaning is not clear
> to me.
> 
> I have WARN_LOGFILE turned on, and attached are the warnings
> corresponding to the two scenarios.
> 
> So is something broken, or am I misconfigured? Opinions?

It helps to know which version of doxygen you are using and on which platform/OS.

Also check this:
http://doxygen.10944.n7.nabble.com/FILTER-PATTERNS-vs-INPUT-FILTER-td3873.html

Regards,
  Dimitri

[Doxygen-users] FILTER_PATTERNS not working?

[Clayton <cla...@gm...>]

Hi guys,

Take for instance this Visual Basic project:

	https://github.com/mbedded-ninja/AltiumScriptCentral

and using this plugin filter:

	https://github.com/sevoku/doxygen-vb-filter

In Doxyfile, if I put:

FILE_PATTERNS = *.vbs
INPUT_FILTER = /path/to/plugins/visual_basic/vbfilter.sh
FILTER_PATTERNS =

it works, I get output. However if I use these settings:

FILE_PATTERNS = *.vbs
INPUT_FILTER = 
FILTER_PATTERNS = *.vbs=/path/to/plugins/visual_basic/vbfilter.sh

nothing happens except a lot more warnings, whose meaning is not clear
to me.

I have WARN_LOGFILE turned on, and attached are the warnings
corresponding to the two scenarios.

So is something broken, or am I misconfigured? Opinions?

Clayton

Re: [Doxygen-users] browser support - for HTML output ?

[Dimitri v. H. <do...@gm...>]

> On 09 Sep 2015, at 0:55 , Monique Semp <mon...@ea...> wrote:
> 
> > Is there a list anywhere that says what the browser support is for Doxygen’s HTML output (from Doxygen 1.8.10)? Or barring that, is there an explanation of which version of HTML is output?

Doxygen outputs XHTML 1.0 transitional (or HTML 4.01) compatible output.

>  
> Hmm... no reply. I guess this isn’t a simple thing to answer. Does anyone have any suggestions for what we *can* say about browser support for viewers of Doxygen’s HTML output, even if it’s a very small list of browsers/versions that we know are fully supported (and then I’d just include info along the lines of, “Other browsers may work but have not been tested.”?

Any version of the major browsers (IE,Chrome,Firefox,Safari) released in the last 5 years should work.
Other and older browsers may also work, but may not handle the dynamic stuff as well (e.g. the tree view and client side searching).

Regards,
  Dimitri

Re: [Doxygen-users] browser support - for HTML output ?

[Monique S. <mon...@ea...>]

> Is there a list anywhere that says what the browser support is for Doxygen’s HTML output (from Doxygen 1.8.10)? Or barring that, is there an explanation of which version of HTML is output?

Hmm... no reply. I guess this isn’t a simple thing to answer. Does anyone have any suggestions for what we *can* say about browser support for viewers of Doxygen’s HTML output, even if it’s a very small list of browsers/versions that we know are fully supported (and then I’d just include info along the lines of, “Other browsers may work but have not been tested.”?

-Monique

Re: [Doxygen-users] image issues - alignment, bold for nearby text, loses \ref link...

[Monique S. <mon...@ea...>]

> Why not? Did you try with the example I provided? It should work fine 
> there, and there should be
no reason why \ref cannot by used inside a HTML table. It doesn't work if 
you would put the table in
a \htmlonly...\endhtmlonly block of course, but I assume you didn't do that.

Well, I went contrary to the logical assumption, and I had surrounded the 
<table/> with \htmlonly and \endhtmlonly, largely because that's how I'd 
originally coded the DoxyS page's contents. Perhaps this was unnecessary way 
back when (2010), but I don't recall and don't need to bother tracking that 
down.

So yes, when I removed the \htmlonly and \endhtmlonly commands, the \image 
and \ref commands worked fine inside the <table> code.

But... the class that was used changed. Without the \htmlonly, the class is 
"doxtable", but with the \htmlonly, the class is unspecified, which I've 
interpreted to mean simply "table".

So when I omit the \htmlonly tag (and closing \endhtmlonly), and include the 
class="table" in the <table> element, I get the desired output. So that's 
what I'll go with.

I assume by extension that Doxygen does not parse anything in an \htmlonly 
block, and so that's why the \image and \ref commands didn't work. So thanks 
for explaining that important point!

-Monique 

Re: [Doxygen-users] image issues - alignment, bold for nearby text, loses \ref link...

[Dimitri v. H. <do...@gm...>]

Hi Monique,

> On 08 Sep 2015, at 21:04 , Monique Semp <mon...@ea...> wrote:
> 
> I've got what I need, but it did require a bit of tweaking.
> 
> The HTML syntax didn't work with the \ref Doxygen commands.

Why not? Did you try with the example I provided? It should work fine there, and there should be
no reason why \ref cannot by used inside a HTML table. It doesn't work if you would put the table in
a \htmlonly...\endhtmlonly block of course, but I assume you didn't do that.

Regards,
  Dimitri

Re: [Doxygen-users] Doxygen-users Digest, Vol 112, Issue 3

[woody <kn...@re...>]

At 12:25 PM 9/8/2015 -0400, you wrote:
>On Fri, Sep 4, 2015 at 11:53 AM, 
><<mailto:dox...@li...>dox...@li...> 
>wrote:
>Date: Fri, 4 Sep 2015 09:00:14 +0100
>From: Frank Peelo <<mailto:f2...@ei...>f2...@ei...>
>Subject: Re: [Doxygen-users] Another question....
>
>So Doxygen
>*should* use the names in the prototype, instead of the ones in the .c
>file.
>
>
>I would expect Doxygen to use the parameter names I document. That is, if 
>I put my Doxygen "mark up" on the function definition, I would expect it 
>to use the parameter names in the function definition. If I put my Doxygen 
>"mark up" on the prototype, I would expect it to use the parameter names 
>in the prototype.

and if you are running it on one without documents for the first time?  It 
*should* use the one in the function, because names are optional in the 
prototypes.
Here is some documentation that would argue strongly for use of the 
function, rather than the prototype.


The ANSI Solution

The ANSI standard's solution to the problems of mismatched arguments is to 
permit the function declaration to declare the variable types, too. The 
result is a function prototype—a declaration that states the return type, 
the number of arguments, and the types of those arguments. To indicate that 
imax() requires two int arguments, you can declare it with either of the 
following prototypes:

int imax(int, int);

int imax(int a, int b);


The first form uses a comma-separated list of types. The second adds 
variable names to the types. Remember that the variable names are dummy 
names and don't have to match the names used in the function definition.

With this information at hand, the compiler can check to see whether the 
function call matches the prototype. Are there the right number of 
arguments? Are they the correct type? If there is a type mismatch and if 
both types are numbers, the compiler converts the values of the actual 
arguments to the same type as the formal arguments. For example, imax(3.0, 
5.0) becomes imax(3, 5). We've modified Listing 9.4 to use a function 
prototype. The result is shown in Listing 9.5.



>On the other hand, I have not encountered this issue as the coding 
>standards my team and I work under require the prototypes to exactly match 
>the definitions.
>
>------------------------------------------------------------------------------
>_______________________________________________
>Doxygen-users mailing list
>Dox...@li...
>https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] image issues - alignment, bold for nearby text, loses \ref link...

[Monique S. <mon...@ea...>]

I've got what I need, but it did require a bit of tweaking.

The HTML syntax didn't work with the \ref Doxygen commands. So when I 
replace them with regular <a href></a> markup, the links worked fine. But 
the links are not in bold as they are when Doxygen creates links to pages, 
so somewhat less than desirable. So I looked at the generated source and 
found that the class for Doxygen links is "el", so I added the following to 
the <a href...> element, and now I've got exactly what I want :-):

class = "el"

The Markdown syntax works as you described, and Doxygen's commands are 
properly implemented -- I hadn't realized that the text I was adding was 
being interpreted by Doxygen as the caption to the image. Thanks for that 
explanation! But if only I could get rid of the header row and table cell 
borders. I've googled a bit and found other postings for this wish in 
StackOverflow, but no solutions for the basic Markdown that I'm assuming is 
used by Doxygen. Any ideas?

Putting an image and associated text/links on the same line in the .page 
file still puts the image on a separate line in the output, which I'm 
guessing is not changeable except by editing the css for the image class, 
which would likely have unintended consequences?. So I'll abandon that 
approach.

Thanks so much for the speedy reply, Dimitri,
-Monique 

Re: [Doxygen-users] image issues - alignment, bold for nearby text, loses \ref link...

[Dimitri v. H. <do...@gm...>]

Hi Monique,

Here are two ways to achieve what you want:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/** @mainpage

Using Markdown syntax:

| image | info |
|-------|------|
\image html image-name.png  "" | Text that leads in to the page link \ref pagename.
\image html image2-name.png "" | More text \ref pagename2.

Using HTML syntax:

<table>
<tr><th>image
    <th>info
<tr><td>\image html image-name.png
    <td>Text that leads in to
        the page link \ref pagename.
<tr><td>\image html image2-name.png
    <td>More text \ref pagename2.
</table>

*/

/** @page pagename
 *  A page
 */

/** @page pagename2
 *  Another page
 */
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Note that if you plan to put more than just plain text in the table cells, 
the HTML syntax is more robust and flexible.

Also note the "" after \image to introduce an empty caption, 
if omitted the rest of the line is seen as the image's caption!

Regards,
  Dimitri

> On 08 Sep 2015, at 20:01 , Monique Semp <mon...@ea...> wrote:
> 
> Hello, Doxygen users,
>  
> I’m using Doxygen 1.8.10 on Win 7, and am having trouble getting an image to be included without affecting the format/alignment of accompanying text, as well as suppressing proper output of a \ref link to another .page file.
>  
> In my Mainpage.page file, I want to include a 2-column tabular presentation, but not include any actual table headers or cell borders, where the first column contains images and the second column contains text (and links to other page files). But everything I try ends up with three problems:
>  
> 1. The image and subsequent text is output as two “rows” with center justification.
> 2. The text is output as bold for no apparent reason.
> 3. The link to the desired page disappears, and the <page-name> instead of the page’s title ends up in the output.
>  
> I tried plain text, as follows:
>  
> \image html image-name.jpg Text that leads in to the page link \ref <page-name>.
> \image html image2-name.jpg More text \ref <page-name2>.
>  
> Then I tried a table just to see if that would help (which is how I had it in the DoxyS project that I’m now porting to Doxygen). But that results in all the problems above, with all the output being put into the first column (even though clearly the table coding places the text in the second column):
>  
> | image | info |
> |-------|------|
> \image html image-name.jpg | Text that leads in to the page link \ref <page-name>.
> \image html iamge2-name | More text \ref <page-name2>.
>  
> The images are found just fine (and Doxygen copies them to the expected output/html folder), and when I delete the images, the page references work as expected.
>  
> Any suggestions?
>  
> Thanks very much,
> -Monique
>  
> ------------------------------------------------------------------------------
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

[Doxygen-users] image issues - alignment, bold for nearby text, loses \ref link...

[Monique S. <mon...@ea...>]

Hello, Doxygen users,

I’m using Doxygen 1.8.10 on Win 7, and am having trouble getting an image to be included without affecting the format/alignment of accompanying text, as well as suppressing proper output of a \ref link to another .page file.

In my Mainpage.page file, I want to include a 2-column tabular presentation, but not include any actual table headers or cell borders, where the first column contains images and the second column contains text (and links to other page files). But everything I try ends up with three problems:

1. The image and subsequent text is output as two “rows” with center justification.
2. The text is output as bold for no apparent reason.
3. The link to the desired page disappears, and the <page-name> instead of the page’s title ends up in the output.

I tried plain text, as follows:

\image html image-name.jpg Text that leads in to the page link \ref <page-name>.
\image html image2-name.jpg More text \ref <page-name2>.

Then I tried a table just to see if that would help (which is how I had it in the DoxyS project that I’m now porting to Doxygen). But that results in all the problems above, with all the output being put into the first column (even though clearly the table coding places the text in the second column):

| image | info |
|-------|------|
\image html image-name.jpg | Text that leads in to the page link \ref <page-name>.
\image html iamge2-name | More text \ref <page-name2>.

The images are found just fine (and Doxygen copies them to the expected output/html folder), and when I delete the images, the page references work as expected.

Any suggestions?

Thanks very much,
-Monique

Re: [Doxygen-users] Doxygen-users Digest, Vol 112, Issue 3

[Ron W <ron...@gm...>]

On Fri, Sep 4, 2015 at 11:53 AM, <
dox...@li...> wrote:

> Date: Fri, 4 Sep 2015 09:00:14 +0100
> From: Frank Peelo <f2...@ei...>
> Subject: Re: [Doxygen-users] Another question....
>
> So Doxygen
> *should* use the names in the prototype, instead of the ones in the .c
> file.
>

I would expect Doxygen to use the parameter names I document. That is, if I
put my Doxygen "mark up" on the function definition, I would expect it to
use the parameter names in the function definition. If I put my Doxygen
"mark up" on the prototype, I would expect it to use the parameter names in
the prototype.

On the other hand, I have not encountered this issue as the coding
standards my team and I work under require the prototypes to exactly match
the definitions.

Re: [Doxygen-users] Another question....

[Jeremy R. <jro...@gm...>]

The easiest way to avoid this problem ist to copy the header in the .c 
file and paste it at the end of the .h file. You don't have to type 
anything except the ";", so it's almost no work either.
Jerry

[Doxygen-users] Inline documentation of last function parameter

[Vaclav P. <wen...@gm...>]

Hello,

I'm using inline descriptions for function parameters/arguments but the
last parameter description goes to the function's description (to the right
function, to the end of description).

int a_function(
    int arg_1,       ///< first argument
    int arg_2);        ///< second argument

I see that the issue is that the the comment is after ); so the function
"parameter section" ended and when I use:

int a_function(
    int arg_1,       ///< first argument
    int arg_2        ///< second argument
    );

it works as expected, same for @param.

Is there a way how to use the coding style with ); on the same line as last
function parameter and at the same time use also the inline parameter
descriptions with Doxygen?

I'm using Doxygen 1.8.9.1 (with C code).

Thanks,
Vaclav

Re: [Doxygen-users] more odd behavior

[Brian H. <bhe...@pi...>]

Woody,

Doxygen does not write documentation for you; it formats and cross-references documentation you have written.

Doxygen generating a cross-reference to "control::V2" (which is a common convention to referring to a struct type member[1]) for the expression table_pointer->V2 is exactly what it's supposed to do.  

If you disagree, please provide actual samples, e.g. the content you are feeding to Doxygen and the output it is generating, along with an example of what you want it to generate.  There may yet be a way to achieve your goals.

Regards,
-Brian

[1] C does not have a language construct for referring to a member of a type because it's unnecessary; there's no such thing as inheritance or polymorphism in the language like there is in C++.  In C++, you very well might have to fully-qualify a member to access it.  Consider:

   typedef struct {
      int V1;
   } control;

In C++, you could write sizeof(control::V1) and get back the same as if you wrote sizeof(int)--you are referring to the type directly, not an instance of the type.  In code terms, you could do something like this:

  assert(sizeof(control::V1) == sizeof(int)); // Fail mightily if someone redefines V1

That would not be possible in C.  You would have to have an instance, like so:

   control one_of_them;
   assert(sizeof(one_of_them.V1) == sizeof(int));

Or you could get clever and do this to save stack:

   assert(sizeof(((control *)0)->V1) == sizeof(int));

Re: [Doxygen-users] more odd behavior

[Monique S. <mon...@ea...>]

> Perhaps it needs a set of options     use only C syntax, and use
descriptions from within the function body, and use the actual function
header rather than the prototype.

I don't know if it will take care of the specific issues that you've been 
describing, but there is (in Doxygen 1.8.10, and I think for many, many 
earlier versions) an option in the Doxygen config file, 
OPTIMIZE_OUTPUT_FOR_C.

Perhaps that will help?

-Monique 

[Doxygen-users] more odd behavior

[woody <kn...@re...>]

what causes this?

there is a
structure  control
	{
int V1;
int V2;
};

a declaration
struct control control_arrays;

within a function, a declaration of a pointer to the structure

struct control * table_pointer;

	table_pointer=control_arrays
i.e. a pointer is set to point to a control structure, called   control_arrays

	there is a reference to
           table_pointer->V1

This gets put in the HTML as
     control::V1

First of all, this is NOT a reference to control directly.  it 
is      table_pointer->V1
So what should be put in front of the function is

     table_pointer->V1        which is the reference used in the function, not
     control::V1                  which is a class member, and there are no 
classes here.
Once again, there is a disconnect between *what is used in the function* 
and what doxygen picks up.  Yes, doxygen figures out that table_pointer 
points to a control structure, but since this is NOT C++, and there are NO 
classes defined, it should NOT use a C++ type indentifier.
What this has forced me to do, since doxygen is failing to put the 
references into the .rtf file,
is to go to the HTML docs, copy the   "Refers to   section, paste that into 
notepad, and reselct it  and copy it to the the clipboard, to get rid of 
the linkages, so it is straight text, then past it into the RTF file.
THEN I have to take a lot of time to correct it so it actually documents 
what is in the function.

I find this not only puzzling, but very frustrating.

Why isn't this thing smart enough to actually use what is in the function 
when producing documentation.

Perhaps it needs a set of options     use only C syntax, and use 
descriptions from within the function body, and use the actual function 
header rather than the prototype.

Re: [Doxygen-users] Another question....

[woody <kn...@re...>]

At 03:38 PM 9/4/2015 +0000, you wrote:
>Content-Language: en-US
>Content-Type: multipart/alternative;
> 
>boundary="_000_acddece4335344f69994c1160549d3aePineMailboxLANGROUPloca_"
>
> From the peanut gallery: Seems to me a reasonable thing to have as an 
> option in the doxygen configuration, the option for parameter names to be 
> taken from the definition rather than the prototype.  With that said, the 
> \param special command s first argument is the parameter name.  I haven t 
> tried it, but it seems that you could specify the name you want used.
>
>
>
>Also as you noted yourself at the start, differing parameter names between 
>prototype and definition is a bad practice which harms both usability and 
>maintainability.  Why is it being done?

Because I wrote this code long ago, when I was not thinking about it....

>  Users of a function ought to be looking at the prototype, not the 
> definition, so if anything, the prototype ought to have the more 
> appropriate names.

I really disagree with this.  I'm oldschool, anti- C++.  I absolutely hate 
relying on anyone elses code.  I want the full source, so I can see what is 
going on, remove bloat etc.
Because I work in the deep embedded at the metal level, memory size is 
crucial.  So I am not going to be looking at the prototype.  Indeed the 
only use I have for prototypes is as a quick
way to jump to the body of the code.  I use a fantastic editor,
Source Insight, and can just select the prototype name and jump to the 
function, or select the name of a function in a call, and jump to the 
prototype or the definition.  Makes for easy
navigation

The program I am generating full documentation on, is 15K of binary, 
running in a 8051 with 16K of flash.  There is no room for C++ overhead, 
and the like.
At this level of programming, you want to see each an every line of 
code.  You also have to abuse coding practices to save memory space at times.
Abusing coding practices, like falling from one case directly into another 
in a switch statement, at times can be advantageous and useful, but not 
considered good programming
practice.

I will say, that the way doxygen works by using headers, has a major 
problem, when the prototypes don't even have an identifier in them,
but the function does, and the body of the function references them.  The 
way it is now, this just flat falls on it's face, forcing the user to have 
to edit the output from
doxygen heavily to fix things like this....

And at the moment, I am the sole programmer, and it is likely to stay that 
way until I retire.  THEN the documentation has to be good enough that the 
guy coming in behind me, can understand and
maintain it.




>
>
>From: woody [mailto:kn...@re...]
>Sent: Friday, September 04, 2015 10:55 AM
>To: Frank Peelo; dox...@li...
>Subject: Re: [Doxygen-users] Another question....
>
>
>
>At 09:00 AM 9/4/2015 +0100, Frank Peelo wrote:
>If you're really going to have different parameter names, the ones in the 
>header should be the ones documented. The documentation is for people who 
>are going to use the function;
>
>Precisely, that is why it should be the FUNCTION ACTUAL HEADER
>the people working on the function body can read the code. People using 
>the function can see the .h file, which has the prototype,
>
>Nope.  In this case the prototype is in the C code.  The target audience 
>for this documentation is management.
>HOWEVER: In this case, what they will see is not the C code, but a 
>detailed verbal english description of the code. (My boss refuses
>to learn any C code, yet he wants a detailed spec specifying what the 
>program is doing in English.)
>The html however, will allow direct access to the body of the file, and 
>when it says that
>
>for function foo the input parameters are   int offtime    and offtime is 
>not used or referenced in the code, then that is a problem.
>The "references" section of the html header lists all references used in 
>the module.  When it says  off    and there is no   off in the
>code, nor in the header, that sends you off on a tangent trying to find 
>where in the hell  off  is in the code.
>So the parameter list that is in the documentation for the specific 
>function, SHOULD match the function, or it leads to confusion.
>
>The disconnect is that it uses the prototype and states that those 
>parameters are used in the function, when indeed, there may not be ANY 
>values with that name.
>
>Consider this:
>
>foo (int, int,int,char);      // a prototype with no identifiers, which is 
>quite legal
>
>foo (int time, int off, int on, char flag)
>
>The current way of doing it would result in
>
>foo
>       int
>       int
>       int
>
>Which does not help with understanding the function.  In this case it 
>should be
>
>foo
>     int time
>     int off
>     int on
>     char flag
>
>
>so doxygen SHOULD use the actual name in the function, not the prototype, 
>because the prototype can be written with NOT NAME AT ALL for the parameters.
>and may not have access to the .c code; if they do have that, they 
>shouldn't need to read it. So Doxygen *should* use the names in the 
>prototype, instead of the ones in the .c file.
>
>Frank
>
>On 03/09/15 21:16, woody wrote:
>
>It seems that Doxygen uses the prototype definition when it creates 
>documentation for a function in the html and rtf files.
>
>For example,
>
>The actual definition of initiate_beep
>static void initiate_beep (int duration,int off, char count)
>{
>// code body
>}
>
>the prototype:
>static void initiate_beep (int duration,int offtime,char count);
>
>
>
>
>
>The compiler is just fine with this, because all it cares about is the 
>type.  However, doxygen picks up the prototype, and uses that as the 
>header for the html and in the rtf file,
>and puts only the body of the code under the header, showing the prototype 
>as the parameters, which of course can cause problems in understanding and 
>documenting code if the programmer
>used different names for the same type.
>
>of course in the body of the code, it is just   off    so *really* doxygen 
>SHOULD be using the actual function definition, if there is one.
>that is, if there is a function that matches the prototype as far as 
>variable types, then the definition line where the function is actually 
>found, should be used to
>show the calling parameters, not the prototype.
>
>This is easy to check.  Just create a function and a prototype, use 
>different names for the same type parameters, and run through doxygen.
>
>Doxygen should document code *as written*  or in construction terms "as 
>built" rather than "as planned".
>prototypes are "as planned" items, actual functions are "as written".
>
>And YES, before anyone says anything else, IT IS BAD PRACTICE to use 
>variable names that are different between function and prototype....
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>------------------------------------------------------------------------------
>
>Monitor Your Dynamic Infrastructure at Any Scale With Datadog!
>
>Get real-time metrics from all of your servers, apps and tools
>
>in one place.
>
>SourceForge users - Click here to start your Free Trial of Datadog now!
>
><http://pubads.g.doubleclick.net/gampad/clk?id=241902991&iu=/4140>http://pubads.g.doubleclick.net/gampad/clk?id=241902991&iu=/4140
>
>
>
>
>
>
>
>
>
>
>
>
>
>_______________________________________________
>
>Doxygen-users mailing list
>
><mailto:Dox...@li...>Dox...@li...
>
>https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>
>------------------------------------------------------------------------------
>_______________________________________________
>Doxygen-users mailing list
><mailto:Dox...@li...>Dox...@li...
>https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>------------------------------------------------------------------------------
>_______________________________________________
>Doxygen-users mailing list
>Dox...@li...
>https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] Another question....

[Brian H. <bhe...@pi...>]

>From the peanut gallery: Seems to me a reasonable thing to have as an option in the doxygen configuration, the option for parameter names to be taken from the definition rather than the prototype.  With that said, the \param special command's first argument is the parameter name.  I haven't tried it, but it seems that you could specify the name you want used.

Also as you noted yourself at the start, differing parameter names between prototype and definition is a bad practice which harms both usability and maintainability.  Why is it being done?  Users of a function ought to be looking at the prototype, not the definition, so if anything, the prototype ought to have the more appropriate names.

From: woody [mailto:kn...@re...]
Sent: Friday, September 04, 2015 10:55 AM
To: Frank Peelo; dox...@li...
Subject: Re: [Doxygen-users] Another question....

At 09:00 AM 9/4/2015 +0100, Frank Peelo wrote:

If you're really going to have different parameter names, the ones in the header should be the ones documented. The documentation is for people who are going to use the function;

Precisely, that is why it should be the FUNCTION ACTUAL HEADER


the people working on the function body can read the code. People using the function can see the .h file, which has the prototype,

Nope.  In this case the prototype is in the C code.  The target audience for this documentation is management.
HOWEVER: In this case, what they will see is not the C code, but a detailed verbal english description of the code. (My boss refuses
to learn any C code, yet he wants a detailed spec specifying what the program is doing in English.)
The html however, will allow direct access to the body of the file, and when it says that

for function foo the input parameters are   int offtime    and offtime is not used or referenced in the code, then that is a problem.
The "references" section of the html header lists all references used in the module.  When it says  off    and there is no   off in the
code, nor in the header, that sends you off on a tangent trying to find where in the hell  off  is in the code.
So the parameter list that is in the documentation for the specific function, SHOULD match the function, or it leads to confusion.

The disconnect is that it uses the prototype and states that those parameters are used in the function, when indeed, there may not be ANY values with that name.

Consider this:

foo (int, int,int,char);      // a prototype with no identifiers, which is quite legal

foo (int time, int off, int on, char flag)

The current way of doing it would result in

foo
      int
      int
      int

Which does not help with understanding the function.  In this case it should be

foo
    int time
    int off
    int on
    char flag


so doxygen SHOULD use the actual name in the function, not the prototype, because the prototype can be written with NOT NAME AT ALL for the parameters.


and may not have access to the .c code; if they do have that, they shouldn't need to read it. So Doxygen *should* use the names in the prototype, instead of the ones in the .c file.

Frank

On 03/09/15 21:16, woody wrote:

It seems that Doxygen uses the prototype definition when it creates documentation for a function in the html and rtf files.

For example,

The actual definition of initiate_beep
static void initiate_beep (int duration,int off, char count)
{
// code body
}

the prototype:
static void initiate_beep (int duration,int offtime,char count);


The compiler is just fine with this, because all it cares about is the type.  However, doxygen picks up the prototype, and uses that as the header for the html and in the rtf file,
and puts only the body of the code under the header, showing the prototype as the parameters, which of course can cause problems in understanding and documenting code if the programmer
used different names for the same type.

of course in the body of the code, it is just   off    so *really* doxygen SHOULD be using the actual function definition, if there is one.
that is, if there is a function that matches the prototype as far as variable types, then the definition line where the function is actually found, should be used to
show the calling parameters, not the prototype.

This is easy to check.  Just create a function and a prototype, use different names for the same type parameters, and run through doxygen.

Doxygen should document code *as written*  or in construction terms "as built" rather than "as planned".
prototypes are "as planned" items, actual functions are "as written".

And YES, before anyone says anything else, IT IS BAD PRACTICE to use variable names that are different between function and prototype....




------------------------------------------------------------------------------

Monitor Your Dynamic Infrastructure at Any Scale With Datadog!

Get real-time metrics from all of your servers, apps and tools

in one place.

SourceForge users - Click here to start your Free Trial of Datadog now!

http://pubads.g.doubleclick.net/gampad/clk?id=241902991&iu=/4140



_______________________________________________

Doxygen-users mailing list

Dox...@li...<mailto:Dox...@li...>

https://lists.sourceforge.net/lists/listinfo/doxygen-users

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