/**< comments in header files */

eastwind · January 21, 2020, 20:33

A number of header files comment struct fields with /**< comments.

What does this denote? I could guess but I won't as I can think of several possibilities.

There's nothing about it in the coding guidelines I found by searching, and searching on angband **< didn't turn up anything.

Nick · January 21, 2020, 21:19

It's for building source documentation with doxygen. Here is the current source documentation for the latest build.

As an example, in the documenation for player.h, compare the descriptions of struct quest and struct player_race.

The comment headers above functions that look like this:

Code:

/**
 * Chooses a room template of a particular kind at random.
 * \param typ template room type - currently unused
 * \return a pointer to the room template
 */

are another example of doxygen instructions; this one gives this doxygen output.

Note that this is far from completely done throughout the codebase.

eastwind · January 21, 2020, 23:19

Thanks, something like that was one of my guesses.

January 21, 2020, 20:33	#1
eastwind Apprentice Join Date: Dec 2019 Location: Mexico, undisclosed location Posts: 79	/< comments in header files /* A number of header files comment struct fields with /< comments. What does this denote? I could guess but I won't as I can think of several possibilities. There's nothing about it in the coding guidelines I found by searching, and searching on angband < didn't turn up anything.

January 21, 2020, 21:19	#2
Nick Vanilla maintainer Join Date: Apr 2007 Location: Canberra, Australia Age: 55 Posts: 8,648 Donated: $60	It's for building source documentation with doxygen. Here is the current source documentation for the latest build. As an example, in the documenation for player.h, compare the descriptions of struct quest and struct player_race. The comment headers above functions that look like this: Code: /** * Chooses a room template of a particular kind at random. * \param typ template room type - currently unused * \return a pointer to the room template */ are another example of doxygen instructions; this one gives this doxygen output. Note that this is far from completely done throughout the codebase. __________________ One for the Dark Lord on his dark throne In the Land of Mordor where the Shadows lie.

Thread Tools
Show Printable Version Email this Page
Display Modes
Linear Mode Switch to Hybrid Mode Switch to Threaded Mode

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Spell browser lost its header	PowerWyrm	Development	0	June 10, 2011 10:40
A plea for comments	Derakon	Development	4	May 30, 2011 18:20
A Few Comments about V	Malatar	Vanilla	20	January 5, 2010 23:40
3.1.0 Comments/Observations	evariste	Vanilla	6	January 17, 2009 03:25
3.10 Comments	awldune	Vanilla	3	January 11, 2009 15:29

January 21, 2020, 23:19	#3
eastwind Apprentice Join Date: Dec 2019 Location: Mexico, undisclosed location Posts: 79	Thanks, something like that was one of my guesses.

Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)