Skip to content

Doxygen comments fixes #5372

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

Merged
merged 3 commits into from
Nov 9, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doxyfile_options
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places.
# The default value is: My Project.

PROJECT_NAME = "My Project"
PROJECT_NAME = "Mbed OS Reference"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is also needed in the json version

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please point me to which json file I should add this change? Then the group changes are only to make navigation through the API docs easier. It doesn't change or move any APIs or the groups. See the attached image. It shows how the grouping/API looks like with these changes. Earlier everything was showing up in the index.html page itself and this change cleans up lot of those. Its based on our discussion to align things like how HAL group was organized.
api_groups

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

doxyfile_options.json

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sg- The contents of json file is as below -
{
"ENABLE_PREPROCESSING": "YES",
"MACRO_EXPANSION": "YES",
"EXPAND_ONLY_PREDEF": "NO",
"SEARCH_INCLUDES": "YES",
"INCLUDE_PATH": "",
"INCLUDE_FILE_PATTERNS": "",
"PREDEFINED": "DOXYGEN_ONLY DEVICE_ANALOGIN DEVICE_ANALOGOUT DEVICE_CAN DEVICE_ETHERNET DEVICE_EMAC DEVICE_FLASH DEVICE_I2C DEVICE_I2CSLAVE DEVICE_I2C_ASYNCH DEVICE_INTERRUPTIN DEVICE_LOWPOWERTIMER DEVICE_PORTIN DEVICE_PORTINOUT DEVICE_PORTOUT DEVICE_PWMOUT DEVICE_RTC DEVICE_TRNG DEVICE_SERIAL DEVICE_SERIAL_ASYNCH DEVICE_SERIAL_FC DEVICE_SLEEP DEVICE_SPI DEVICE_SPI_ASYNCH DEVICE_SPISLAVE DEVICE_STORAGE "MBED_DEPRECATED_SINCE(f, g)=" "MBED_ENABLE_IF_CALLBACK_COMPATIBLE(F, M)="",
"EXPAND_AS_DEFINED": "",
"SKIP_FUNCTION_MACROS": "NO",
"EXCLUDE_PATTERNS": "/tools/ /targets/ /FEATURE_/* /features/mbedtls/ /features/storage/ /features/unsupported/ /features/filesystem/ /BUILD/ /rtos/TARGET_CORTEX/rtx/* /cmsis/ /features/FEATURES_"
}
Looks like not changes are needed in that, can you please confirm?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you dont add that here, it will not be present in the online hosted version. All changes to the local doxyfile need to be accounted for in the json version. Otherwise it is assumed that the tool defaults will be used.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes, I see your point now, updated json as well now. Please review.


# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
Expand Down
1 change: 1 addition & 0 deletions doxygen_options.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
{
"PROJECT_NAME": "Mbed OS Reference",
"ENABLE_PREPROCESSING": "YES",
"MACRO_EXPANSION": "YES",
"EXPAND_ONLY_PREDEF": "NO",
Expand Down
7 changes: 7 additions & 0 deletions drivers/UARTSerial.h
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,13 @@

namespace mbed {

/** \addtogroup drivers */

/** Class providing buffered UART communication functionality using separate circular buffer for send and receive channels
*
* @ingroup drivers
*/

class UARTSerial : private SerialBase, public FileHandle, private NonCopyable<UARTSerial> {

public:
Expand Down
16 changes: 14 additions & 2 deletions platform/ATCmdParser.h
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,15 @@
#include <cstdarg>
#include "Callback.h"

namespace mbed {

/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_ATCmdParser ATCmdParser class
* @{
*/

/**
* Parser class for parsing AT commands
*
Expand All @@ -43,8 +52,6 @@
* @endcode
*/

namespace mbed {

class ATCmdParser : private NonCopyable<ATCmdParser>
{
private:
Expand Down Expand Up @@ -299,6 +306,11 @@ class ATCmdParser : private NonCopyable<ATCmdParser>
*/
bool process_oob(void);
};

/**@}*/

/**@}*/

} //namespace mbed

#endif //MBED_ATCMDPARSER_H
10 changes: 8 additions & 2 deletions platform/CThunk.h
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@

/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_CThunk CThunk class
* @{
*/
/* General C++ Object Thunking class
*
* - allows direct callbacks to non-static C++ class functions
Expand Down Expand Up @@ -73,13 +77,11 @@

/* IRQ/Exception compatible thunk entry function */
typedef void (*CThunkEntry)(void);
/** @}*/

/**
* Class for created a pointer with data bound to it
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template<class T>
class CThunk
Expand Down Expand Up @@ -243,5 +245,9 @@ class CThunk
}
};

/**@}*/

/**@}*/

#endif/*__CTHUNK_H__*/

19 changes: 14 additions & 5 deletions platform/CallChain.h
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,17 @@
#include <string.h>

namespace mbed {


typedef Callback<void()> *pFunctionPointer_t;
class CallChainLink;

/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_CallChain CallChain class
* @{
*/

/** Group one or more functions in an instance of a CallChain, then call them in
* sequence using CallChain::call(). Used mostly by the interrupt chaining code,
Expand Down Expand Up @@ -60,12 +70,7 @@ namespace mbed {
* chain.call();
* }
* @endcode
* @ingroup platform
*/

typedef Callback<void()> *pFunctionPointer_t;
class CallChainLink;

class CallChain : private NonCopyable<CallChain> {
public:
/** Create an empty chain
Expand Down Expand Up @@ -183,6 +188,10 @@ class CallChain : private NonCopyable<CallChain> {
CallChainLink *_chain;
};

/**@}*/

/**@}*/

} // namespace mbed

#endif
Expand Down
16 changes: 8 additions & 8 deletions platform/Callback.h
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,15 @@

namespace mbed {
/** \addtogroup platform */

/** @{*/
/**
* \defgroup platform_Callback Callback class
* @{
*/

/** Callback class based on template specialization
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template <typename F>
class Callback;
Expand Down Expand Up @@ -67,7 +70,6 @@ namespace detail {
/** Callback class based on template specialization
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template <typename R>
class Callback<R()> {
Expand Down Expand Up @@ -642,7 +644,6 @@ class Callback<R()> {
/** Callback class based on template specialization
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template <typename R, typename A0>
class Callback<R(A0)> {
Expand Down Expand Up @@ -1218,7 +1219,6 @@ class Callback<R(A0)> {
/** Callback class based on template specialization
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template <typename R, typename A0, typename A1>
class Callback<R(A0, A1)> {
Expand Down Expand Up @@ -1795,7 +1795,6 @@ class Callback<R(A0, A1)> {
/** Callback class based on template specialization
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template <typename R, typename A0, typename A1, typename A2>
class Callback<R(A0, A1, A2)> {
Expand Down Expand Up @@ -2373,7 +2372,6 @@ class Callback<R(A0, A1, A2)> {
/** Callback class based on template specialization
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template <typename R, typename A0, typename A1, typename A2, typename A3>
class Callback<R(A0, A1, A2, A3)> {
Expand Down Expand Up @@ -2952,7 +2950,6 @@ class Callback<R(A0, A1, A2, A3)> {
/** Callback class based on template specialization
*
* @note Synchronization level: Not protected
* @ingroup platform
*/
template <typename R, typename A0, typename A1, typename A2, typename A3, typename A4>
class Callback<R(A0, A1, A2, A3, A4)> {
Expand Down Expand Up @@ -4546,6 +4543,9 @@ Callback<R(A0, A1, A2, A3, A4)> callback(const volatile U *obj, R (*func)(const
return Callback<R(A0, A1, A2, A3, A4)>(func, obj);
}

/**@}*/

/**@}*/

} // namespace mbed

Expand Down
10 changes: 9 additions & 1 deletion platform/CircularBuffer.h
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,15 @@

namespace mbed {
/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_CircularBuffer CircularBuffer functions
* @{
*/

/** Templated Circular buffer class
*
* @note Synchronization level: Interrupt safe
* @ingroup platform
*/
template<typename T, uint32_t BufferSize, typename CounterType = uint32_t>
class CircularBuffer {
Expand Down Expand Up @@ -112,6 +116,10 @@ class CircularBuffer {
volatile bool _full;
};

/**@}*/

/**@}*/

}

#endif
Expand Down
10 changes: 10 additions & 0 deletions platform/CriticalSectionLock.h
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,13 @@

namespace mbed {

/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_CriticalSectionLock CriticalSectionLock functions
* @{
*/

/** RAII object for disabling, then restoring, interrupt state
* Usage:
* @code
Expand Down Expand Up @@ -65,6 +72,9 @@ class CriticalSectionLock {
}
};

/**@}*/

/**@}*/

} // namespace mbed

Expand Down
11 changes: 11 additions & 0 deletions platform/DeepSleepLock.h
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@

namespace mbed {

/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_DeepSleepLock DeepSleepLock functions
* @{
*/

/** RAII object for disabling, then restoring the deep sleep mode
* Usage:
Expand Down Expand Up @@ -82,6 +88,11 @@ class DeepSleepLock {
}
};

/**@}*/

/**@}*/


}

#endif
8 changes: 7 additions & 1 deletion platform/DirHandle.h
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,11 @@

namespace mbed {
/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_DirHandle DirHandle functions
* @{
*/


/** Represents a directory stream. Objects of this type are returned
Expand All @@ -40,7 +45,6 @@ namespace mbed {
*
* @note to create a directory, @see Dir
* @note Synchronization level: Set by subclass
* @ingroup platform
*/
class DirHandle : private NonCopyable<DirHandle> {
public:
Expand Down Expand Up @@ -142,7 +146,9 @@ class DirHandle : private NonCopyable<DirHandle> {
virtual void seekdir(off_t location) { seek(location); }
};

/**@}*/

/**@}*/
} // namespace mbed

#endif /* MBED_DIRHANDLE_H */
19 changes: 13 additions & 6 deletions platform/FileBase.h
Original file line number Diff line number Diff line change
Expand Up @@ -27,19 +27,22 @@ typedef int FILEHANDLE;
#include "platform/NonCopyable.h"

namespace mbed {
/** \addtogroup platform */
/** @{*/


typedef enum {
FilePathType,
FileSystemPathType
} PathType;
/** @}*/

/** \addtogroup platform */
/** @{*/
/**
* @class FileBase
* @ingroup platform
* \defgroup platform_FileBase FileBase class
* @{
*/
/** Class FileBase
*
*/

class FileBase : private NonCopyable<FileBase> {
public:
FileBase(const char *name, PathType t);
Expand All @@ -62,6 +65,10 @@ class FileBase : private NonCopyable<FileBase> {
const PathType _path_type;
};

/**@}*/

/**@}*/

} // namespace mbed

#endif
Expand Down
11 changes: 10 additions & 1 deletion platform/FileHandle.h
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ typedef int FILEHANDLE;

namespace mbed {
/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_FileHandle FileHandle functions
* @{
*/


/** Class FileHandle
Expand All @@ -36,7 +41,6 @@ namespace mbed {
*
* @note to create a file, @see File
* @note Synchronization level: Set by subclass
* @ingroup platform
*/
class FileHandle : private NonCopyable<FileHandle> {
public:
Expand Down Expand Up @@ -254,6 +258,11 @@ class FileHandle : private NonCopyable<FileHandle> {

std::FILE *fdopen(FileHandle *fh, const char *mode);

/**@}*/

/**@}*/


} // namespace mbed

#endif
Loading