Skip to content

Commit eebef10

Browse files
LeStarchLeStarch
authored
lestarch: updating .hpp and .md files for clean doxygen run (nasa#676)
1 parent 5ff62bd commit eebef10

File tree

51 files changed

+267
-190
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+267
-190
lines changed

‎.github/actions/Dockerfile

+5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
FROM nasafprime/fprime-base:latest
22

33
# Copies your code file from your action repository to the filesystem path `/` of the container
4+
USER root
5+
RUN apt-get update && apt-get install -y --no-install-recommends doxygen && \
6+
apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && pip3 --no-cache-dir install fprime-tools fprime-gds
47
COPY entrypoint.sh /entrypoint.sh
8+
COPY autodoc.bash /autodoc.bash
9+
USER fprime
510

611
# Code file to execute when the docker container starts up (`entrypoint.sh`)
712
ENTRYPOINT ["/entrypoint.sh"]

‎.github/actions/autodoc.bash

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
#!/bin/bash
2+
3+
# Exit when any command fails
4+
set -e
5+
set -x
6+
7+
cd "$GITHUB_WORKSPACE"
8+
REMOTE="${1:-origin}"
9+
git config --local user.email "nasa-fprime[bot]@users.noreply.github.com"
10+
git config --local user.name "nasa-fprime[bot]"
11+
git fetch "${REMOTE}" release/documentation
12+
git fetch "${REMOTE}" devel
13+
git checkout release/documentation
14+
git merge "${REMOTE}"/devel
15+
${GITHUB_WORKSPACE}/docs/doxygen/generate_docs.bash
16+
git add -Af "${GITHUB_WORKSPACE}/docs"
17+
18+
19+
git commit -m "Autodoc on $(date)" 1>/dev/null
20+
git push "${REMOTE}"

‎.github/actions/entrypoint.sh

+8-3
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,12 @@
22

33
# Exit when any command fails
44
set -e
5-
5+
set -x
66
cd "$GITHUB_WORKSPACE"
7-
"$GITHUB_WORKSPACE/ci/master.bash" QUICK
8-
"$GITHUB_WORKSPACE/ci/master.bash" STATIC
7+
if [ "$GITHUB_WORKFLOW" != "Autodocs" ]
8+
then
9+
"$GITHUB_WORKSPACE/ci/master.bash" QUICK
10+
"$GITHUB_WORKSPACE/ci/master.bash" STATIC
11+
else
12+
/autodoc.bash
13+
fi

‎.github/actions/github-autodocs.yml

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name: 'fprime Automatic Documentation'
2+
description: 'Runs continuous documentation updates on fprime'
3+
runs:
4+
using: 'docker'
5+
image: 'Dockerfile'
6+
entrypoint: '/autodoc.bash'
7+
with:
8+
github_token: ${{ secrets.GITHUB_TOKEN }}
9+

‎.github/actions/spelling/expect.txt

+2-3
Original file line numberDiff line numberDiff line change
@@ -616,7 +616,6 @@ gcgandhi
616616
gcov
617617
gdiplus
618618
gencode
619-
gendoc
620619
genfile
621620
GENHUB
622621
GENREP
@@ -882,7 +881,6 @@ LCHILD
882881
ldl
883882
lemstarch
884883
len
885-
leq
886884
lestarch
887885
levelname
888886
lflag
@@ -1332,7 +1330,7 @@ Rcv
13321330
rcvd
13331331
RCVTIMEO
13341332
RDONLY
1335-
RDWR
1333+
rdwr
13361334
Readback
13371335
readdir
13381336
READERROR
@@ -1818,6 +1816,7 @@ vals
18181816
valud
18191817
ve
18201818
venv
1819+
VERSIONED
18211820
versioning
18221821
VFILE
18231822
vhd

‎.github/workflows/autodocs.yml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: Autodocs
2+
on:
3+
push:
4+
branches:
5+
- "devel"
6+
7+
jobs:
8+
build:
9+
name: Autodocumentation
10+
runs-on: ubuntu-20.04
11+
steps:
12+
- name: checkout
13+
uses: actions/[email protected]
14+
with:
15+
fetch-depth: 5
16+
- uses: ./.github/actions/
17+
id: github-autodocs

‎CFDP/Checksum/Checksum.hpp

+3-3
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,9 @@ namespace CFDP {
6363

6464
//! Update the checksum value by accumulating the words in the data
6565
void update(
66-
const U8 *const data, //! The data
67-
const U32 offset, //! The offset of the start of the data, relative to the start of the file
68-
const U32 length //! The length of the data in bytes
66+
const U8 *const data, //!< The data
67+
const U32 offset, //!< The offset of the start of the data, relative to the start of the file
68+
const U32 length //!< The length of the data in bytes
6969
);
7070

7171
//! Get the checksum value

‎Drv/BlockDriver/docs/sdd.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
## 1. Introduction
55

6-
The `Drv::BlockDriver` is a demonstration component that loops back data buffers from `Ref::SendBuffApp` [HTML](../../../Ref/SendBuffApp/docs/sdd.html) [MD](../../../Ref/SendBuffApp/docs/sdd.md) to `Ref::RecvBuffApp` [HTML](../../../Ref/RecvBuffApp/docs/sdd.html) [MD](../../../Ref/RecvBuffApp/docs/sdd.md) It also emulates a timing interrupt driven by the public method `void callIsr(void)`.
6+
The `Drv::BlockDriver` is a demonstration component that loops back data buffers. It also emulates a timing interrupt driven by the public method `void callIsr(void)`.
77

88
## 2. Requirements
99

@@ -26,7 +26,7 @@ The `Drv::BlockDriver` component has the following component diagram:
2626

2727
## 4. Dictionaries
2828

29-
Dictionaries [HTML](BlockDriver.html) [MD](BlockDriver.md)
29+
TBD
3030

3131
## 5. Module Checklists
3232

‎Drv/Ip/SocketReadTask.hpp

+1
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ class SocketReadTask {
4646
* \param name: name of the task
4747
* \param priority: priority of the started task. See: Os::Task::start.
4848
* \param stack: stack size provided to the task. See: Os::Task::start.
49+
* \param reconnect: automatically reconnect socket when closed. Default: true.
4950
* \param cpuAffinity: cpu affinity provided to task. See: Os::Task::start.
5051
*/
5152
void startSocketTask(const Fw::StringBase &name,

‎Drv/Ip/UdpSocket.hpp

+1-4
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,6 @@ class UdpSocket : public IpSocket {
7171
*
7272
* \param hostname: socket uses for incoming transmissions. Must be of form x.x.x.x
7373
* \param port: port socket uses for incoming transmissions. Must NOT be 0.
74-
* \param send_timeout_seconds: send timeout seconds portion
75-
* \param send_timeout_microseconds: send timeout microseconds portion. Must be less than 1000000
7674
* \return status of configure
7775
*/
7876
SocketIpStatus configureRecv(const char* hostname, const U16 port);
@@ -81,8 +79,7 @@ class UdpSocket : public IpSocket {
8179

8280
/**
8381
* \brief bind the UDP to a port such that it can receive packets at the previously configured port
84-
* \param address: address in x.x.x.x notation
85-
* \param port: port to bind to
82+
* \param fd: socket file descriptor used in bind
8683
* \return status of the bind
8784
*/
8885
SocketIpStatus bind(NATIVE_INT_TYPE fd);

‎Drv/SocketIpDriver/SocketIpDriverComponentImpl.hpp

+2-2
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@ namespace Drv {
6060
//! Open up the socket port, ready for communications
6161
//!
6262
SocketIpStatus configure(
63-
const char* hostname,
64-
U16 port,
63+
const char* hostname, /*!< Hostname of remote server */
64+
U16 port, /*!< Port of remote server */
6565
const bool send_udp = SOCKET_SEND_UDP, /*!< Send down using UDP. Default: read from configuration HPP*/
6666
const U32 timeout_seconds = SOCKET_TIMEOUT_SECONDS, /*!< Timeout(S). Default: from configuration HPP*/
6767
const U32 timeout_microseconds = SOCKET_TIMEOUT_MICROSECONDS /*!< Timeout(uS). Default: from configuration HPP*/

‎Fw/Buffer/Buffer.hpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ class Buffer : public Fw::Serializable {
109109
//! deserializes the pointer to said data, the size, and context. This is done for efficiency in moving around data,
110110
//! and is the primary usage of Fw::Buffer. To deserialize the wrapped data, use either the data pointer accessor
111111
//! or the serialize buffer base representation and deserialize from that.
112-
//! \param serialBuffer: serialize buffer to read data into
112+
//! \param buffer: serialize buffer to read data into
113113
//! \return: status of serialization
114114
Fw::SerializeStatus deserialize(Fw::SerializeBufferBase& buffer);
115115

‎Fw/Cmd/docs/sdd.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
\page FwCmdFwCmdResponseCmdReg Fw::Cmd / Fw::CmdResponse /Fw::CmdReg Ports
2-
# Fw::Cmd / Fw::CmdResponse /Fw::CmdReg Ports
1+
\page FwCmdFwCmdResponseFwCmdReg Fw::Cmd / Fw::CmdResponse / Fw::CmdReg Ports
2+
# Fw::Cmd / Fw::CmdResponse / Fw::CmdReg Ports
33

44
## 1. Introduction
55

‎Fw/Log/docs/sdd.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\page FwLogLogText Fw::Log / Fw::LogText Ports
1+
\page FwLogLogText Fw::Log, Fw::LogText Ports
22
# Fw::Log / Fw::LogText Ports
33

44
## 1. Introduction

‎Fw/Logger/Logger.hpp

+23-15
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,17 @@ namespace Fw {
1818
* Function called on the logger to log a message. This is abstract virtual method and
1919
* must be supplied by the subclass. This logger object should be registered with the
2020
* Fw::Log::registerLogger function.
21-
* \param const char* fmt: format string in which to place arguments
22-
* \param POINTER_CAST a1: first argument. (Default: 0)
23-
* \param POINTER_CAST a2: second argument. (Default: 0)
24-
* \param POINTER_CAST a3: third argument. (Default: 0)
25-
* \param POINTER_CAST a4: forth argument. (Default: 0)
26-
* \param POINTER_CAST a5: fifth argument. (Default: 0)
27-
* \param POINTER_CAST a6: sixth argument. (Default: 0)
21+
* \param fmt: format string in which to place arguments
22+
* \param a0: zeroth argument. (Default: 0)
23+
* \param a1: first argument. (Default: 0)
24+
* \param a2: second argument. (Default: 0)
25+
* \param a3: third argument. (Default: 0)
26+
* \param a4: forth argument. (Default: 0)
27+
* \param a5: fifth argument. (Default: 0)
28+
* \param a6: sixth argument. (Default: 0)
29+
* \param a7: seventh argument. (Default: 0)
30+
* \param a8: eight argument. (Default: 0)
31+
* \param a9: ninth argument. (Default: 0)
2832
*/
2933
virtual void log(
3034
const char* fmt,
@@ -43,13 +47,17 @@ namespace Fw {
4347
/**
4448
* Logs a message using the currently specified static logger. If a logger is not
4549
* registered, then the log message is dropped.
46-
* \param const char* fmt: format string in which to place arguments
47-
* \param POINTER_CAST a1: first argument. (Default: 0)
48-
* \param POINTER_CAST a2: second argument. (Default: 0)
49-
* \param POINTER_CAST a3: third argument. (Default: 0)
50-
* \param POINTER_CAST a4: forth argument. (Default: 0)
51-
* \param POINTER_CAST a5: fifth argument. (Default: 0)
52-
* \param POINTER_CAST a6: sixth argument. (Default: 0)
50+
* \param fmt: format string in which to place arguments
51+
* \param a0: zeroth argument. (Default: 0)
52+
* \param a1: first argument. (Default: 0)
53+
* \param a2: second argument. (Default: 0)
54+
* \param a3: third argument. (Default: 0)
55+
* \param a4: forth argument. (Default: 0)
56+
* \param a5: fifth argument. (Default: 0)
57+
* \param a6: sixth argument. (Default: 0)
58+
* \param a7: seventh argument. (Default: 0)
59+
* \param a8: eight argument. (Default: 0)
60+
* \param a9: ninth argument. (Default: 0)
5361
*/
5462
static void logMsg(
5563
const char* fmt,
@@ -68,7 +76,7 @@ namespace Fw {
6876
/**
6977
* Registers the static logger for use with the Fw::Log::logMsg function. This must be
7078
* a subclass of Fw::Log.
71-
* Log* logger: logger to log to when Fw::Log::logMsg is called.
79+
* \param logger: logger to log to when Fw::Log::logMsg is called.
7280
*/
7381
static void registerLogger(Logger* logger);
7482

‎Fw/Trap/TrapHandler.hpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ namespace Fw {
1919
* Handles the incoming trap.
2020
* Note: if user does not supply an implementer of this
2121
* function, a do-nothing version will be run.
22-
* \param U32 trap: trap number
22+
* \param trap: trap number
2323
*/
2424
virtual void doTrap(U32 trap) = 0;
2525
};

‎Fw/Types/MallocAllocator.hpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ namespace Fw {
4444
//! Deallocate memory
4545
/*!
4646
* \param identifier the memory segment identifier (not used)
47-
* \ptr the pointer to memory returned by allocate()
47+
* \param ptr the pointer to memory returned by allocate()
4848
*/
4949
void deallocate(
5050
const NATIVE_UINT_TYPE identifier,

‎Fw/Types/MemAllocator.hpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ namespace Fw {
5757
//! Deallocate memory
5858
/*!
5959
* \param identifier the memory segment identifier (if needed)
60-
* \ptr the pointer to memory returned by allocate()
60+
* \param ptr the pointer to memory returned by allocate()
6161
*/
6262
virtual void deallocate(
6363
const NATIVE_UINT_TYPE identifier,

‎Fw/Types/MmapAllocator.hpp

+14
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,25 @@
1717

1818
namespace Fw {
1919

20+
//! Fw::MmapAllocator is an implementation of the Fw::MemAllocator interface that back memory with a read and write
21+
//! capable anonymous memory mapped region. This class is currently not useful for mapping to a file.
2022
class MmapAllocator: public MemAllocator {
2123
public:
24+
//! Constructor with no arguments
25+
//!
2226
MmapAllocator();
27+
//! Destructor with no arguments
2328
virtual ~MmapAllocator();
29+
30+
//! Allocate memory using the mmap allocator
31+
//! \param identifier: identifier to use with allocation
32+
//! \param size: size of memory to be allocated
33+
//! \param recoverable: (output) is this memory recoverable after a reset. Always false for mmap.
2434
void *allocate(const NATIVE_UINT_TYPE identifier, NATIVE_UINT_TYPE &size, bool& recoverable);
35+
36+
//! Deallocation of memory using the mmap allocator
37+
//! \param identifier: identifier used at allocation
38+
//! \param ptr: pointer to memory being deallocated
2539
void deallocate(const NATIVE_UINT_TYPE identifier, void* ptr);
2640

2741
private:

‎Os/Baremetal/Queue.cpp

+4-21
Original file line numberDiff line numberDiff line change
@@ -33,21 +33,11 @@ class BareQueueHandle {
3333
//!< Actual queue used to store
3434
BufferQueue m_queue;
3535
};
36-
/**
37-
* Queue should be initialized with a NULL handle
38-
*/
36+
3937
Queue::Queue() :
4038
m_handle(static_cast<POINTER_CAST>(NULL))
4139
{ }
4240

43-
/**
44-
* Create a new queue. The will also recreate the queue if it exists.
45-
* WARNING: this must be called only during initialization.
46-
* \param const Fw::StringBase &name: name of the queue
47-
* \param NATIVE_INT_TYPE depth: depth of the queue
48-
* \param NATIVE_INT_TYPE msgSize: message size
49-
* \return Queue::QueueStatus
50-
*/
5141
Queue::QueueStatus Queue::createInternal(const Fw::StringBase &name, NATIVE_INT_TYPE depth, NATIVE_INT_TYPE msgSize) {
5242
BareQueueHandle* handle = reinterpret_cast<BareQueueHandle*>(this->m_handle);
5343
// Queue has already been created... remove it and try again:
@@ -70,9 +60,7 @@ Queue::QueueStatus Queue::createInternal(const Fw::StringBase &name, NATIVE_INT_
7060
#endif
7161
return QUEUE_OK;
7262
}
73-
/**
74-
* Cleans up the dynamic memory of this queue
75-
*/
63+
7664
Queue::~Queue() {
7765
// Clean up the queue handle:
7866
BareQueueHandle* handle = reinterpret_cast<BareQueueHandle*>(this->m_handle);
@@ -81,9 +69,7 @@ Queue::~Queue() {
8169
}
8270
this->m_handle = static_cast<POINTER_CAST>(NULL);
8371
}
84-
/**
85-
* Helper function for sending non-blocking requests.
86-
*/
72+
8773
Queue::QueueStatus bareSendNonBlock(BareQueueHandle& handle, const U8* buffer, NATIVE_INT_TYPE size, NATIVE_INT_TYPE priority) {
8874
FW_ASSERT(handle.m_init);
8975
BufferQueue& queue = handle.m_queue;
@@ -95,10 +81,7 @@ Queue::QueueStatus bareSendNonBlock(BareQueueHandle& handle, const U8* buffer, N
9581
}
9682
return status;
9783
}
98-
/**
99-
* Helper function for sending blocking requests.
100-
* WARNING: since this is for baremetal, this *always* ASSERTS
101-
*/
84+
10285
Queue::QueueStatus bareSendBlock(BareQueueHandle& handle, const U8* buffer, NATIVE_INT_TYPE size, NATIVE_INT_TYPE priority) {
10386
FW_ASSERT(handle.m_init);
10487
BufferQueue& queue = handle.m_queue;

0 commit comments

Comments
 (0)