Subject: Re: commit - doxygen comments, new layout - please look
From: John L. Clark (jlc6@po.cwru.edu)
Date: Fri Jan 26 2001 - 11:50:42 CST
Jesper,
Taking a look at the new layout of the comments, it seems to me that
things appear a bit cluttered, as you mentioned, possibly because the
comments need to be kept at the same indentation level with the function
declarations. Otherwise, the actual function itself seems hidden. It
also indicates the fact that we're within the class structure (which is
why we indent the body of a class to begin with). Here's how I think it
should look:
class fp_Container
{
public:
/*!
Create container
\param iType Container type
\param pSectionLayout Section layout type used for this container
*/
fp_Container(UT_uint32 iType, fl_SectionLayout* pSectionLayout);
/*!
Destruct container
\note The lines (fp_Line) in the container are not
destructed. They are owned by the logical hierarchy (i.e.,
fl_BlockLayout), not the physical hierarchy.
*/
~fp_Container();
/*!
Return container type
\return Type
*/
inline UT_uint32 getType(void) const { return m_iType; }
/*!
Set page
\param pPage Page container is located on
*/
void setPage(fp_Page*);
/*!
Rest of fp_Container below...
*/
};
I think that this looks really good, and gives a good reference to the
functions. And this way, you can easily find where the function is with
respect to the corresponding comment.
I have a couple questions about the actual content of the comments, too.
When should it be necessary to use the \return doxygen structure? For
example, why do you have the line `\return Type' in the comments for
getType()? What information does that provide that looking at the code
doesn't?
Take care,
John
This archive was generated by hypermail 2b25 : Fri Jan 26 2001 - 11:50:38 CST