Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Few doc comments #6

Open
dkfellows opened this issue Feb 19, 2024 · 0 comments
Open

Few doc comments #6

dkfellows opened this issue Feb 19, 2024 · 0 comments

Comments

@dkfellows
Copy link

You have not many doc comments. Though there's some other comments that could probably be repurposed. (Doxygen-style comments are a little finicky, but putting API documentation in your header files is a very good idea.)

I recommend putting brief descriptions (@brief) in header files (together with the likes of @param and @return) but leaving detailed descriptions (@details) for the .cpp files where you do the implementations. That seems to produce the best results overall.

For example, in PCC_Writer.h (no @return because there's no result value):

/*! 
 * @brief Write out the structure after the program has computed its contents.
 * @param new_cells_design Structure to write out
 */
void PCC_Writer(CellsDesign &new_cells_design);

In PCC_Writer.cpp:

/**
 * @details
 * Read PCC Writer specifications from the writer.ini file and output of the
 * current configuration to the screen and .log file.
 */
void PCC_Writer(CellsDesign &new_cells_design) {
    ....
This was referenced Feb 19, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant