'Re: [Doxygen-users] doxygen query'

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       doxygen-users
Subject:    Re: [Doxygen-users] doxygen query
From:       Paul Joireman <joireman () fnal ! gov>
Date:       2007-06-15 19:47:09
Message-ID: 4672ECBD.8050309 () fnal ! gov
[Download RAW message or body]

[Attachment #2 (multipart/alternative)]


Donovan,

This also occurs with version 1.5.2 (the latest, at least on Windows).  
I've tried multiple ways to eliminate the behavior, using different 
switches in the Doxyfile and the \brief special command without success. 

It appears that what is intended is that the programmer will only have a 
brief description near the method declaration and a more detailed 
description near the method definition, or everything at the declaration 
and nothing at the definition.   The first case is seen for your Y 
class, where the brief description is taken from the declaration but the 
more detailed from the definition.   However, once you have a detailed 
description at the declaration, that seems to be used.

Couldn't find this as a reported bug following a brief search (bad pun 
unintentional).

Paul

Donovan Rebbechi wrote:

>I have two queries about doxygen (for both examples, I have JAVADOC_AUTOBRIEF
>set, all other options are left at the default config as produced by doxygen -g
>version 1.5.1):
>
>I have attached a simple example, which demonstrates the issues here
>
>(1) documentation states:  (see class X in my example)
>
> Furthermore, if there is one brief description before a declaration and one 
> before a definition of a code item, only the one before the declaration will
> be used. If the same occurs for a detailed description, the one before the 
> definition is preferred and the one before the declaration will be ignored.
>
>The second sentence of this statement does not appear to reflect the current
>behaviour (testing on 1.5.1). I have the one before the declaration being 
>preferred (for both brief and detailed).
>
>(2)  (see class Y in my example)
>    When there is a brief given before the declaration, and a detailed given 
>    before a definition, it appears that the first line of the comment block
>    preceding the definition is treated as a "brief" hence not included in
>    the documentation. This seems counter intuitive. Perhaps the entire 
>    comment preceding the definition should be treated as detailed instead ?
>
>Cheers,
>  
>
>------------------------------------------------------------------------
>
>
>/**
> *  Class X. This illustrates that when descriptions are provided both at the 
> *  declaration and definition, the description near the definition is always
> *  used (with both the brief and detailed description), producing output like
> *  this: 
> * 
> *  Brief description in the declaration
> *  Detailed description in the declaration
> * 
> *   This appears to be 
> *  different from the behaviour specified in the documentation, which 
> *  predicts this:
> *
> *  Brief description in the declaration.
> *  Detailed description in the definition.
> *
> */
>class X
>{
>public:
>    /**
>     * Brief description in declaration.
>     * Detailed description in declaraion.
>     */
>    void foo();
>
>};
>
>/**
> * Brief description in definition.
> * Detailed description in definition.
> */
>void X::foo() {}
>
>/**
> *  Class Y. This illustrates that when JAVADOC_AUTOBRIEF is set, 
> *  if we put a brief description near the declaration, and a detailed
> *  description near the definition, the first sentence of the comment 
> *  block at the definition is ignored (suspect that it's treated as 
> *  brief, and hence overruled by the brief description at the declaration)
> */
>class Y
>{
>public:
>    /**
>     * Brief description.
>     */
>    void bar();
>};
>
>
>
>/**
> * This doesn't show up if autobrief is on.
> * The detailed description starts here.
> */
>void Y::bar() {}
>
>  
>
>------------------------------------------------------------------------
>
>-------------------------------------------------------------------------
>This SF.net email is sponsored by DB2 Express
>Download DB2 Express C - the FREE version of DB2 express and take
>control of your XML. No limits. Just data. Click to get it now.
>http://sourceforge.net/powerbar/db2/
>  
>
>------------------------------------------------------------------------
>
>_______________________________________________
>Doxygen-users mailing list
>Doxygen-users@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/doxygen-users
>  
>

[Attachment #5 (text/html)]

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
  <title></title>
</head>
<body bgcolor="#ffffff" text="#000000">
Donovan,<br>
<br>
This also occurs with version 1.5.2 (the latest, at least on Windows).&nbsp;
I've tried multiple ways to eliminate the behavior, using different
switches in the Doxyfile and the \brief special command without
success.&nbsp; <br>
<br>
It appears that what is intended is that the programmer will only have
a brief description near the method declaration and a more detailed
description near the method definition, or everything at the
declaration and nothing at the definition.&nbsp;&nbsp; The first case is seen for
your Y class, where the brief description is taken from the declaration
but the more detailed from the definition.&nbsp;&nbsp; However, once you have a
detailed description at the declaration, that seems to be used.<br>
<br>
Couldn't find this as a reported bug following a brief search (bad pun
unintentional).<br>
<br>
Paul<br>
<br>
Donovan Rebbechi wrote:<br>
<blockquote cite="mid20070615185115.GA27623@panix.com" type="cite">
  <pre wrap="">I have two queries about doxygen (for both examples, I have \
JAVADOC_AUTOBRIEF set, all other options are left at the default config as produced \
by doxygen -g version 1.5.1):

I have attached a simple example, which demonstrates the issues here

(1) documentation states:  (see class X in my example)

 Furthermore, if there is one brief description before a declaration and one 
 before a definition of a code item, only the one before the declaration will
 be used. If the same occurs for a detailed description, the one before the 
 definition is preferred and the one before the declaration will be ignored.

The second sentence of this statement does not appear to reflect the current
behaviour (testing on 1.5.1). I have the one before the declaration being 
preferred (for both brief and detailed).

(2)  (see class Y in my example)
    When there is a brief given before the declaration, and a detailed given 
    before a definition, it appears that the first line of the comment block
    preceding the definition is treated as a "brief" hence not included in
    the documentation. This seems counter intuitive. Perhaps the entire 
    comment preceding the definition should be treated as detailed instead ?

Cheers,
  </pre>
  <pre wrap="">
<hr size="4" width="90%">

/**
 *  Class X. This illustrates that when descriptions are provided both at the 
 *  declaration and definition, the description near the definition is always
 *  used (with both the brief and detailed description), producing output like
 *  this: 
 * 
 *  Brief description in the declaration
 *  Detailed description in the declaration
 * 
 *   This appears to be 
 *  different from the behaviour specified in the documentation, which 
 *  predicts this:
 *
 *  Brief description in the declaration.
 *  Detailed description in the definition.
 *
 */
class X
{
public:
    /**
     * Brief description in declaration.
     * Detailed description in declaraion.
     */
    void foo();

};

/**
 * Brief description in definition.
 * Detailed description in definition.
 */
void X::foo() {}

/**
 *  Class Y. This illustrates that when JAVADOC_AUTOBRIEF is set, 
 *  if we put a brief description near the declaration, and a detailed
 *  description near the definition, the first sentence of the comment 
 *  block at the definition is ignored (suspect that it's treated as 
 *  brief, and hence overruled by the brief description at the declaration)
 */
class Y
{
public:
    /**
     * Brief description.
     */
    void bar();
};



/**
 * This doesn't show up if autobrief is on.
 * The detailed description starts here.
 */
void Y::bar() {}

  </pre>
  <pre wrap="">
<hr size="4" width="90%">
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
<a class="moz-txt-link-freetext" \
href="http://sourceforge.net/powerbar/db2/">http://sourceforge.net/powerbar/db2/</a>  \
</pre>  <pre wrap="">
<hr size="4" width="90%">
_______________________________________________
Doxygen-users mailing list
<a class="moz-txt-link-abbreviated" \
href="mailto:Doxygen-users@lists.sourceforge.net">Doxygen-users@lists.sourceforge.net</a>
 <a class="moz-txt-link-freetext" \
href="https://lists.sourceforge.net/lists/listinfo/doxygen-users">https://lists.sourceforge.net/lists/listinfo/doxygen-users</a>
  </pre>
</blockquote>
</body>
</html>


["joireman.vcf" (text/x-vcard)]

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/

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


[prev in list] [next in list] [prev in thread] [next in thread]
Configure | About | News | Add a list | Sponsored by KoreLogic