Fix #559, Resolve doxygen warnings by lbleier-GSFC · Pull Request #648 · nasa/cFE

lbleier-GSFC · 2020-04-28T16:19:29Z

Describe the contribution
Fixes #559, resolving all doxygen warnings

Testing performed
Steps taken to test the contribution:

Fixed warnings as listed in warnings.log
Built documentation using make doc
Observed relevant documentation working correctly

Expected behavior changes
A clear and concise description of how this contribution will change behavior and level of impact.

Documentation links and references will now work properly

Contributor Info - All information REQUIRED for consideration of pull request
Full name and company/organization/center of all contributors ("Personal" if individual work)

Leor Bleier NASA GSFC\Code 582

fsw/cfe-core/src/es/cfe_es_cds.h

skliper · 2020-04-28T16:49:04Z

fsw/cfe-core/src/inc/cfe_sb.h

 ** \param[in]  MsgPtr       A pointer to the message to be sent.  This must point
 **                          to the first byte of the software bus message header
-**                          (#CFE_SB_Msg_t). 
+**                          ("::"CFE_SB_Msg_t). 


Curious why old reference didn't work? What does "::" do?

Part of the autolink system: http://www.doxygen.nl/manual/autolink.html (item 3 under "Links to functions"

I double checked, I'm noticing that the literal "::" appears as well. I missed that, I may need to revisit

Did the # cause an error/warning? Note 3 from that reference seems to say # should work? "For Javadoc compatibility a # may be used instead of a :: in the patterns above."

It was, yes, which is why I changed it, and got no error as a result.

skliper · 2020-04-28T16:49:21Z

fsw/cfe-core/src/inc/cfe_sb.h

 ** \param[in]  MsgPtr       A pointer to the message to be sent.  This must point
 **                          to the first byte of the software bus message header
-**                          (#CFE_SB_Msg_t). 
+**                          ("::"CFE_SB_Msg_t). 


Same comment as above.

skliper · 2020-04-28T16:50:42Z

fsw/cfe-core/src/inc/cfe_sb_msg.h

 **
 **  \par Command Structure
-**       #CFE_SB_CmdHdr_t
+**       cfe_sb.h::CFE_SB_CmdHdr_t


Do these show up as links? Curious why old reference didn't work

skliper · 2020-04-28T16:52:02Z

fsw/cfe-core/src/sb/cfe_sb_priv.h

 ** \par Assumptions, External Events, and Notes:
 **          - For statically defined messages, a function call will not work.  The 
-**            macros #CFE_SB_CMD_HDR_SIZE and #CFE_SB_TLM_HDR_SIZE are available for use 
+**            macros cfe_sb.h::CFE_SB_CMD_HDR_SIZE and cfe_sb.h::CFE_SB_TLM_HDR_SIZE are available for use 


Do these link correctly?

These are not working, I missed them too. Will fix

skliper · 2020-04-28T16:53:03Z

cmake/cfe-common.doxyfile.in

 # Project related configuration options, shared for all cFE doxygen outputs
 #---------------------------------------------------------------------------
 @INCLUDE_PATH          = @MISSION_SOURCE_DIR@
-DOXYFILE_ENCODING      = UTF-8 


Were all deleted settings the defaults?

Where can a user go find what the defaults are?

doxygen will create a config file with the defaults, doxygen -g configfile

Would it be worthwhile to add a comment that says "to see defaults run doxygen -g configfile" ?

As we experienced last week, doxygen knowledge is sparse, and this might help.

It's on the man page...

lbleier-GSFC · 2020-04-28T17:39:28Z

I guess I missed a few of these. I thought they were working. I will need to revisit and push a fix

astrogeco · 2020-05-05T18:34:07Z

@lbleier-GSFC I like the simplification. Can you post a built version of this so we can see how these changes will affect the generated doc?

astrogeco · 2020-05-05T18:34:47Z

When it's ready go ahead and tag with the "ready for CCB" label

lbleier-GSFC · 2020-05-05T20:38:48Z

@lbleier-GSFC I like the simplification. Can you post a built version of this so we can see how these changes will affect the generated doc?

I am not quite sure what you're asking for. The entire documentation? Where would I post it?

skliper · 2020-05-05T20:55:49Z

@lbleier-GSFC I like the simplification. Can you post a built version of this so we can see how these changes will affect the generated doc?

I am not quite sure what you're asking for. The entire documentation? Where would I post it?

Likely just the pdf that gets built from the latex directory.

skliper · 2020-05-05T20:56:20Z

Drag and drop to add it to a comment here

lbleier-GSFC · 2020-05-05T21:13:20Z

@lbleier-GSFC I like the simplification. Can you post a built version of this so we can see how these changes will affect the generated doc?

I am not quite sure what you're asking for. The entire documentation? Where would I post it?

Likely just the pdf that gets built from the latex directory.

Latex doesn't get generated, as per the config file. I don't see any relevant PDFs

skliper · 2020-05-05T21:22:03Z

@lbleier-GSFC I like the simplification. Can you post a built version of this so we can see how these changes will affect the generated doc?

I am not quite sure what you're asking for. The entire documentation? Where would I post it?

Likely just the pdf that gets built from the latex directory.

Latex doesn't get generated, as per the config file. I don't see any relevant PDFs

I wonder why we don't for doc, we do for osalguide and usersguide. Want to try enabling it and see if you can build the pdf? Enable latex, enter the build/doc/detaildesign/latex directory and type make, if it works it'll create a refman.pdf (or whatever name it's set to) which can be dropped here.

lbleier-GSFC · 2020-05-05T21:58:25Z

@lbleier-GSFC I like the simplification. Can you post a built version of this so we can see how these changes will affect the generated doc?

I am not quite sure what you're asking for. The entire documentation? Where would I post it?

Likely just the pdf that gets built from the latex directory.

Latex doesn't get generated, as per the config file. I don't see any relevant PDFs

I wonder why we don't for doc, we do for osalguide and usersguide. Want to try enabling it and see if you can build the pdf? Enable latex, enter the build/doc/detaildesign/latex directory and type make, if it works it'll create a refman.pdf (or whatever name it's set to) which can be dropped here.

I am trying to build but it's failing, I'll need to investigate

lbleier-GSFC · 2020-05-06T13:43:59Z

@lbleier-GSFC I like the simplification. Can you post a built version of this so we can see how these changes will affect the generated doc?

I managed to build a PDF despite a ton of warnings and make having an error. I am seeing some issues (e.g. all the references for CFE_SB_SubscribeFull() on page 1444), but I can't seem to find this in the source

File:
refman.pdf

astrogeco · 2020-05-06T16:17:53Z

CCB-20200506 - APPROVED, Open new tickets for LaTeX mission docs and missing function documentation.

astrogeco · 2020-05-08T18:12:23Z

CCB-20200506 - APPROVED, Open new tickets for LaTeX mission docs and missing function documentation.

@skliper @lbleier-GSFC did we open tickets for these?

lbleier-GSFC · 2020-05-08T18:16:03Z

CCB-20200506 - APPROVED, Open new tickets for LaTeX mission docs and missing function documentation.

@skliper @lbleier-GSFC did we open tickets for these?

Yes, #682 and #681, looks like the latter has already been fixed in #686

astrogeco · 2020-05-08T19:37:51Z

@lbleier-GSFC can you resolve these conflicts?

lbleier-GSFC · 2020-05-08T19:48:14Z

@lbleier-GSFC can you resolve these conflicts?

I'm not quite sure what the conflict is. Both the cfeapi and cfeglossary sections of main.dox were completely removed and put into their own separate files. I will delete those sections in main.dox

skliper · 2020-05-08T19:53:28Z

I recommend rebasing your changes on top of IC, and resolve conflicts there.

skliper · 2020-05-08T19:54:28Z

Also needs squash

docs/src/cfe_api.dox

skliper · 2020-05-08T21:00:07Z

@astrogeco - Resolved and squashed.

Fix nasa#559, Resolve doxygen warnings

skliper reviewed Apr 28, 2020

View reviewed changes

skliper changed the title ~~Fix559 fixdocwarnings~~ Fix #559, Resolve doxygen warnings Apr 28, 2020

lbleier-GSFC added the CCB:Ready Ready for discussion at the Configuration Control Board (CCB) label May 6, 2020

astrogeco added the CCB-20200506 label May 6, 2020

astrogeco removed the CCB:Ready Ready for discussion at the Configuration Control Board (CCB) label May 6, 2020

skliper added this to the 6.8.0 milestone May 7, 2020

CDKnightNASA mentioned this pull request May 7, 2020

Fix #681, Resolve doxygen warnings for tbl #686

Merged

astrogeco added CCB:Approved Indicates code review and approval by community CCB IC-20200429 labels May 8, 2020

astrogeco added the conflicts label May 8, 2020

skliper reviewed May 8, 2020

View reviewed changes

docs/src/cfe_api.dox Outdated Show resolved Hide resolved

Fix nasa#559, Resolve doxygen warnings

b58ff99

skliper force-pushed the fix559-fixdocwarnings branch from 894e6e0 to b58ff99 Compare May 8, 2020 20:59

skliper removed the conflicts label May 8, 2020

astrogeco merged commit e79d2a7 into nasa:integration-candidate May 8, 2020

skliper pushed a commit to skliper/cFE that referenced this pull request May 11, 2020

Merge pull request nasa#648 from lbleier-GSFC/fix559-fixdocwarnings

c8d8bf8

Fix nasa#559, Resolve doxygen warnings

astrogeco mentioned this pull request May 13, 2020

Integration Candidate COMBINED 2020-04-29 and 2020-05-06 #692

Merged

Conversation

lbleier-GSFC commented Apr 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lbleier-GSFC Apr 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lbleier-GSFC commented Apr 28, 2020

Uh oh!

astrogeco commented May 5, 2020

Uh oh!

astrogeco commented May 5, 2020

Uh oh!

lbleier-GSFC commented May 5, 2020

Uh oh!

skliper commented May 5, 2020

Uh oh!

skliper commented May 5, 2020

Uh oh!

lbleier-GSFC commented May 5, 2020

Uh oh!

skliper commented May 5, 2020

Uh oh!

lbleier-GSFC commented May 5, 2020

Uh oh!

lbleier-GSFC commented May 6, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

astrogeco commented May 6, 2020

Uh oh!

astrogeco commented May 8, 2020

Uh oh!

lbleier-GSFC commented May 8, 2020

Uh oh!

astrogeco commented May 8, 2020

Uh oh!

lbleier-GSFC commented May 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

skliper commented May 8, 2020

Uh oh!

skliper commented May 8, 2020

Uh oh!

Uh oh!

skliper commented May 8, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

lbleier-GSFC commented Apr 28, 2020 •

edited

Loading

lbleier-GSFC Apr 28, 2020 •

edited

Loading

lbleier-GSFC commented May 6, 2020 •

edited

Loading

lbleier-GSFC commented May 8, 2020 •

edited

Loading