I have a problem with documenting the file itself using javadoc style and doxygen. I can generate nice documentation for variables and functions but for the file itself, the doxygen always thinks the header of the file is the documentation for the next immediate variable or macro following it even if that var or macro has its own javadoc comment block. Take the example below:
/**
* MAX9611 Sensor I2C
*
* #author Saeid Yazdani
* #date 01/07/2016
*
*/
#ifndef MAX9611_HPP
#define MAX9611_HPP
#include "stdint.h" //for uint and stuff
/**
* max9611 RS+ ADC value is 0 to 57.3V in 12bit
* so to convert it to real voltage we need this constant 57.3/4096
* this can be used for both RS+ and OUT adc values to be converted to real V
*/
#define MAX9611_VOLT_MUL 0.0139892578125
So, when I generate documentation for this file (using doxygen/doxywizard) the documentation for the defined macro will be replaced by the header of the file.
What is the correct way to do such thing? Is it considered a good practice to document the file itself (with information like description, author, time, version and ...) and if so how to solve the problem that I just described?
Use the \file command.
The Doxygen manual provides this example code:
/** \file file.h
* A brief file description.
* A more elaborated file description.
*/
/**
* A global integer value.
* More details about this value.
*/
extern int globalValue;
and a link to the output:
Related
Is it possible to create aliases of protobuf's scalar types?
For example, I'd like to use Sequence in lieu of string, even though they would be binary equivalent.
My immediate goal is to make documentation (generated with protoc-gen-doc) more readily understandable.
Ideally, this type would be represented in languages that support type checking, but that's not necessary.
Well this will be a bit dull answer but:
No, I'm not aware of such feature existing or having been planned.
You can sort of emulate it by making submessages that contain only a single field, but that will alter the binary representation.
You're not the first asking this though:
Re: [protobuf] does protoc allow you to typedef a scalar ?
Is it possible to define an alias for type (enum or message) in google protobuf?
[Update: Aug 2017. Adapted to the full Go rewrite of protoc-gen-bug, currently 1.0.0-rc]
I don't have an answer for type aliases, but do have one for this:
My immediate goal is to make documentation (generated with protoc-gen-doc) more readily understandable.
And also I want to point out that protoc-gen-doc has been entirely rewritten in Go and now uses Docker for generation instead of apt-get.
I have created some html and markdown demo's of using inline rich formatting within your comments, like adding links, code snippets, tables, bold, italic, etc.
And also describe how you can auto-generate and publish to Github Pages (gh-pages branch) using TravisCI
There are some small bugs that still need to be solved (Aug 2017) for it to be production-ready.
View the demo's + description at:
https://github.com/aschrijver/protoc-gen-doc-example
.
For example having markdown inlined comments like these:
/**
* The **SLEEP** format is designed by the [Dat Project](https://datproject.org)
* to allow for sparse replication, meaning you can efficiently download
* only the metadata and data required to resolve a single byte region
* of a single file, which makes Dat suitable for a wide variety of streaming,
* _real-time_ and large dataset use cases.
*
* To take advantage of this, Dat includes a _network protocol_. It is message
* based and stateless, making it possible to implement on a variety of network
* transport protocols including UDP and TCP.
*
* Both metadata and content registers in **SLEEP** share the exact same
* replication protocol.
*
* Individual messages are encoded using Protocol Buffers and there are ten
* message types in total.
*
* ### Wire Protocol
*
* Over the wire messages are packed in the following lightweight
* container format:
*
* ```
* <varint - length of rest of message>
* <varint - header>
* <message>
* ```
*
* The `header` value is a single `varint` that has two pieces of information,
* the integer type that declares a 4-bit message type (used below), and a
* channel identifier, 0 for metadata and 1 for content.
*
* To generate this varint, you bitshift the 4-bit type integer onto the end of
* the channel identifier, e.g. channel << 4 | <4-bit-type>.
*
* ### Using in NodeJS
*
* The `protocol-bufers` package offers an intuitive javascript API, so you need
* not worry about low-level protocol concepts.
*
* This example demonstrates how you create a feed and start streaming:
*
* ```javascript
* var protocol = require('hypercore-protocol')
* var stream = protocol()
*
* // open a feed specified by a 32 byte key
* var feed = stream.feed(Buffer('deadbeefdeadbeefdeadbeefdeadbeef'))
*
* feed.request({block: 42})
* feed.on('data', function (message) {
* console.log(message) // contains message.index and message.value
* })
*
* stream.pipe(anotherStream).pipe(stream)
* ```
*/
.
Will result in output similar to this:
HypercoreSpecV1_md.proto
The SLEEP format is designed by the Dat
Project to allow for sparse replication,
meaning you can efficiently download only the metadata and data
required to resolve a single byte region of a single file, which makes
Dat suitable for a wide variety of streaming,
real-time and large dataset use cases.
To take advantage of this, Dat includes a network protocol. It is
message based and stateless, making it possible to implement on a
variety of network transport protocols including UDP and TCP.
Both metadata and content registers in SLEEP share the exact same
replication protocol.
Individual messages are encoded using Protocol Buffers and there are
ten message types in total.
Wire Protocol
Over the wire messages are packed in the following lightweight
container format:
<varint - length of rest of message>
<varint - header>
<message>
The header value is a single varint that has two pieces of
information, the integer type that declares a 4-bit message type (used
below), and a channel identifier, 0 for metadata and 1 for content.
To generate this varint, you bitshift the 4-bit type integer onto the
end of the channel identifier, e.g. channel << 4 | <4-bit-type>.
Using in NodeJS
The protocol-bufers package offers an intuitive javascript API, so
you need not worry about low-level protocol concepts.
This example demonstrates how you create a feed and start streaming:
var protocol = require('hypercore-protocol')
var stream = protocol()
// open a feed specified by a 32 byte key
var feed = stream.feed(Buffer('deadbeefdeadbeefdeadbeefdeadbeef'))
feed.request({block: 42})
feed.on('data', function (message) {
console.log(message) // contains message.index and message.value
})
stream.pipe(anotherStream).pipe(stream)
(Note: The hypercore protocol is one of the core specifications of the Dat Project ecosystem of modules for creating decentralized peer-to-peer application designs. I used their .proto file to demonstrate concepts)
I want to connect two related define-makros in my doxygen HTML-documentation in such a way, that they are shown in a single description box.
I hope I can describe clearly how it should look like: Normally every define statement gets its own description box using /** #define <description> */. This results in a description box with the code part in the title line of the box and a short description in the box content.
What I want to do now is to connect two define statements in such a way that they are shown in a single box with a common description. Does anybody knows a way to realize that?
PS: Maby it gets a little bit clearer with this ASCII graphic.
+-------------------------+
| #define PORT 1 |
| #define PORTDIR 0 |
+-------------------------+
| output port definitions |
+-------------------------+
You can group #defines using #name #{ .. #}. Here is a small example. Looks best when also setting SUBGROUPING to NO in the configuration file.
/** #file
* File documentation
*/
/** #name Output ports definitions
* #brief Brief description for the group.
* #{
*/
#define PORT 1 /**< #brief The port number */
#define PORTDIR 0 /**< #brief The port direction */
/** #} */
/** #brief A lonely macro */
#define LONELY 2
When you omit the documentation for the individual macros you get close the what you requested, only the documentation is above and not below the group.
I'd like to use \copydoc to include some values that may change inside a member's brief description.
Unfortunately, everything after the \copydoc command gets excluded from the \brief description and then mangled.
e.g.
/**
* \class macro_num_apples_range
* 5-10
*/
/** \brief an apple tree with \copydoc macro_num_apples_range apples in it.
*/
apple_tree;
Where macro_num_apples_range is a class I've made earlier in the file (with EXCLUDE_SYMBOLS = macro* in the Doxyfile, so that it won't actually appear in Doxygen's output) to act like a variable that can be easily updated.
The desired output of the above being: "an apple tree with 5-10 apples in it." placed in the brief description of the member.
The actual result of the above is that "an apple tree with" ends up in the brief documentation, and then the rest ends up in a mangled state in the detailed documentation like so: "apples in it. 5-10 apples in it."
Generally, I've noticed that very weird things happen if \copydoc is not invoked on its own line.
In fact, an almost-workaround is to do something like:
/**
* \class macro_num_apples_range
* 5-10
*/
/** \brief an apple tree with
*\copydoc macro_num_apples_range
* apples in it.
*/
apple_tree;
In which case the weird doubling of "apples in it." will not occur. However, /brief descriptions only take their content from a single-line comment, so this doesn't quite do the trick.
Am I missing something fundamental about how Doxygen commands work in general, maybe?
Trying to add Code Completion Hints to my own objective-c header files by checking some 3rd library headers.Looking if There is Code Completion Standarts in Xcode5 similar to VisualStudio.
I saw "//! description" (without quotas) working very well.
//! well seems working as a code completion hint
-(void)myMethod:(BOOL)myParam1 (NSString*)myParam2;
My Question 1: how can I add a linebreak ?
//! well seems working as a code completion hint
//! but this second line seems added into first description in code completion hint
-(void)myMethod:(BOOL)myParam1 (NSString*)myParam2;
My Question 2: looking for a standart similar to this
//! <method>myMethod:does something good.</method>
//! <param> (BOOL)myParam1:is first parameter </param>
//! <param> (NSString*)myParam2:is second parameter </param>
-(void)myMethod:(BOOL)myParam1 (NSString*)myParam2;
may you refer me a documentation about "//! description" (without quotas) how to ?
looking some standarts about "how to code add description standarts in xcode for objective-c"
(for sharing any ideas and knowledges;thanks.)
I use javadoc format, which seems to work OK:
/**
* Summary of method.
*
* A bit more detail, if you really must know stuff.
*
* #code
* Some sample code.
* #endcode
*
* #see http://stackoverflow.com
*
* #param p1 A parameter, no less.
* #param p2 Another parameter.
*
* #return YES if it's Wednesday, else NO.
*/
See this article for more.
In this header file, I am getting error: unknown type name uint32, uint16. I am new to Objective-C and I am trying to import a project in Xcode. Build is failing due to the above issues. Google didn't help.Tried adding /stdint/stdint.h in header search path ( xcode unknown type name, unknown type name 'uint8_t', MinGW, Xcode - how to include c library and header file to cocoa project?). Build still failing.
/*-------------------------------------------------------------------------
*
* block.h
* POSTGRES disk block definitions.
*
*
* Portions Copyright (c) 1996-2010, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* $PostgreSQL: pgsql/src/include/storage/block.h,v 1.26 2010/01/02 16:58:08 momjian Exp $
*
*-------------------------------------------------------------------------
*/
#ifndef BLOCK_H
#define BLOCK_H
/*
* BlockNumber:
*
* each data file (heap or index) is divided into postgres disk blocks
* (which may be thought of as the unit of i/o -- a postgres buffer
* contains exactly one disk block). the blocks are numbered
* sequentially, 0 to 0xFFFFFFFE.
*
* InvalidBlockNumber is the same thing as P_NEW in buf.h.
*
* the access methods, the buffer manager and the storage manager are
* more or less the only pieces of code that should be accessing disk
* blocks directly.
*/
typedef uint32 BlockNumber;
#define InvalidBlockNumber ((BlockNumber) 0xFFFFFFFF)
#define MaxBlockNumber ((BlockNumber) 0xFFFFFFFE)
/*
* BlockId:
*
* this is a storage type for BlockNumber. in other words, this type
* is used for on-disk structures (e.g., in HeapTupleData) whereas
* BlockNumber is the type on which calculations are performed (e.g.,
* in access method code).
*
* there doesn't appear to be any reason to have separate types except
* for the fact that BlockIds can be SHORTALIGN'd (and therefore any
* structures that contains them, such as ItemPointerData, can also be
* SHORTALIGN'd). this is an important consideration for reducing the
* space requirements of the line pointer (ItemIdData) array on each
* page and the header of each heap or index tuple, so it doesn't seem
* wise to change this without good reason.
*/
typedef struct BlockIdData
{
uint16 bi_hi;
uint16 bi_lo;
} BlockIdData;
The types one should normally use are named like uint32_t (these are defined in C99, header file stdint.h). All others are non-standard and should be avoided if you can. Now in your case, you can't avoid the non-standard types. So to make your code compile, you need to map the non-standard names to the standard ones like this:
typedef uint32_t uint32;
You need to add this mapping for all of the types used in PostgreSQL. One way would be either to add them to your precompiled header (.pch) file or to create a header with these typedefs that you #include before you include the PostgreSQL headers.
uint32 should UInt32. You'll want to adjust the name or:
typedef UInt32 uint32;
typedef uint32 BlockNumber;