[Doxygen-users] Table of contents breaks when documentation spans multiple comment blocks with same @page

[Jimi D. <jd...@ac...>]

Hi,

I am using 1.8.6 ( on Ubuntu 14.04 ) and I have a C sample file that is 
being used to illustrate the order in which to make certain API calls. 
So , what I get is a C file that has chunks of code and before each code 
section, I am trying to add documentation that explains what is 
happening as well as providing an anchor for a higher up Doxygen page 
that can point to these sections.

What i am finding is that when I split up my Doxygen comments, it breaks 
the @tableofcontents  entry that I have supplied at the top of the C file.

Here are my two files

1.  Top level README.doc

/*! @page top_level   A subpage


@subpage sample_one A Sample

*/



1. Sample C file called sample_one.c at the same level as README.doc



/**
  * @file sample_one.c
  * @author $Format: %an <%ae>$
  * @date   $Format: %ad$
  * @version $Format: %h$
  * @page sample_one Sample One example
  * @tableofcontents
  * @section sample_one_first Some interesting stuff
  *
  * Some random text
  *
  * @section sample_one_two  More interesting stuff
  *
  *
  * @subsection sample_one_two_one  A subsection header
  *
  *
  */


/**
  * @brief A general foo structure
  *
  */
struct foo {
     int a;
     char *b;
}

int
main(int argc, char *argv[] )
{
     struct foo a;

     /**
      * *@page sample_one Sample One example*
      * @section configuring_something
      * @brief Initialization
      *
      */
     Init(a);
}


If I remove the last @page sample_one Sample One example line, then the 
table of contents is provided correctly. However, I would prefer all of 
these separate sections to be included in a subpage that is called 
"sample_one".  This won't happen unless I have the @page sample_one 
sprinkled throughout my .C file so that they are included.



I feel like this is a bug because Doxygen never warns me that processing 
this second @page causes problems.


Thanks for any ideas about what I might be missing and whether this is 
in fact a bug.

-Jimi





-- 
WARNING - This e-mail or its attachments may contain controlled technical 
data or controlled technology within the definition of the International 
Traffic in Arms Regulations (ITAR) or Export Administration Regulations 
(EAR), and are subject to the export control laws of the U.S. Government. 
Transfer of this data or technology by any means to a foreign person, 
whether in the United States or abroad, without an export license or other 
approval from the U.S. Government, is prohibited. The information contained 
in this document is CONFIDENTIAL and property of ACCES I/O Products, Inc. 
Any unauthorized review, use, disclosure or distribution is prohibited 
without express written consent of ACCES I/O Products, Inc. If you are not 
the intended recipient, please contact the sender and destroy all copies of 
the original message and enclosed attachments.