In a header file there is a structure
/* temp example structure*/
typedef struct {
/* #internal */
char *c;
/* #internal */
char *ts;
} j;
If the internal elements of the structure is not documented, doxygen generates warnings.
But it is necessary to not document the internal elements.
So what can be sued.
Tried \internal but it did not work
\internal is used to remove parts of documentation, but use them when you generate internal documentation. You may still want to write documentation for this entries. It is useful when you want to generate full doc for yourself/developers, but generate less detailed (or just omit parts that you can't show because of e.g. NDA) for outside world.
It is used in combination with other doxygen commands, e.g. /// \internal \defgroup foo will show this entire group only for internal doc (INTERNAL_DOCS in doxygen config). You can also use it for structure fields:
struct foo {
int field0; /**< Documented field */
int field1; /**< \internal only documented for internal doc */
};
Field will still be visible in structure doc, but second field will miss any documentation.
You can't define internal block, but you can combine \internal with \defgroup or \section.
Related
Sorry if the question did not make sense. Here is what I am trying to do:
I want to deploy this smart contract (LenseHub) that imports a library that requires data passed to its constructor. This is problematic because I need LenseHub to initialize the contract (a function I can call only after the contract is deployed). If I try to deploy LenseHub without pre-deploying the IERC721Enumerable it will fail obviously. If I can't figure this out I will just inherit IERC721Enumerable and initialize it via the constructor, but would really like to keep the original smart contracts integrity (for testing purposes). Any suggestions on how to do this would be greatly appreciated
Here is the relevant part of the smart contract:
import {IERC721Enumerable} from "#openzeppelin/contracts/token/ERC721/extensions/IERC721Enumerable.sol";
/**
* #title LensHub
* #author Lens Protocol
*
* #notice This is the main entrypoint of the Lens Protocol. It contains governance functionality as well as
* publishing and profile interaction functionality.
*
* NOTE: The Lens Protocol is unique in that frontend operators need to track a potentially overwhelming
* number of NFT contracts and interactions at once. For that reason, we've made two quirky design decisions:
* 1. Both Follow & Collect NFTs invoke an LensHub callback on transfer with the sole purpose of emitting an event.
* 2. Almost every event in the protocol emits the current block timestamp, reducing the need to fetch it manually.
*
* OVERVIEW: The lense protocall is one of the three main solidity contracts compiled. It compiles all of its code imports code into
* one main "hub" from were you can interact with the protocall.
*
*
*/
contract LensHub is
LensNFTBase,
VersionedInitializable,
LensMultiState,
LensHubStorage,
ILensHub
{
uint256 internal constant REVISION = 1;
address internal immutable FOLLOW_NFT_IMPL;
address internal immutable COLLECT_NFT_IMPL;
/**
* #dev This modifier reverts if the caller is not the configured governance address.
*/
modifier onlyGov() {
_validateCallerIsGovernance();
_;
}
/**
* #dev The constructor sets the immutable follow & collect NFT implementations.
*
* #param followNFTImpl The follow NFT implementation address.
* #param collectNFTImpl The collect NFT implementation address.
*/
constructor(address followNFTImpl, address collectNFTImpl) {
if (followNFTImpl == address(0)) revert Errors.InitParamsInvalid();
if (collectNFTImpl == address(0)) revert Errors.InitParamsInvalid();
FOLLOW_NFT_IMPL = followNFTImpl;
COLLECT_NFT_IMPL = collectNFTImpl;
}
/// #inheritdoc ILensHub
function initialize(
string calldata name,
string calldata symbol,
address newGovernance
) external override initializer {
super._initialize(name, symbol);
_setState(DataTypes.ProtocolState.Paused);
_setGovernance(newGovernance);
}
Here is the _function that the initialize function calls:
function _initialize(string calldata name, string calldata symbol) internal {
ERC721Time.__ERC721_Init(name, symbol);
emit Events.BaseInitialized(name, symbol, block.timestamp);
}
Here is the relevent part of the library:
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v4.5.0) (token/ERC721/extensions/IERC721Enumerable.sol)
pragma solidity ^0.8.0;
import "../IERC721.sol";
/**
* #title ERC-721 Non-Fungible Token Standard, optional enumeration extension
* #dev See https://eips.ethereum.org/EIPS/eip-721
*/
interface IERC721Enumerable is IERC721 {
/**
* #dev Returns the total amount of tokens stored by the contract.
*/
function totalSupply() external view returns (uint256);
/**
* #dev Returns a token ID owned by `owner` at a given `index` of its token list.
* Use along with {balanceOf} to enumerate all of ``owner``'s tokens.
*/
function tokenOfOwnerByIndex(address owner, uint256 index) external view returns (uint256);
/**
* #dev Returns a token ID at a given `index` of all the tokens stored by the contract.
* Use along with {totalSupply} to enumerate all tokens.
*/
function tokenByIndex(uint256 index) external view returns (uint256);
}
Here is the constructor of ERC721 that I am trying to pass variables to :
constructor(string memory name_, string memory symbol_) {
_name = name_;
_symbol = symbol_;
}
First of all, don't call the IERC721Enumerable a library - it is just an interface you want to implement in your contract. In the context of solidity, a library has a bit different meaning. The question became misleading in the context of solidity.
Secondly, what you want to achieve may be done in two ways - complicated but more correct and easy but less correct:
The complicated approach requires you to use IERC721Upgradeable and properly upgrade your contact when it is needed. I don't think you need to go this far because using a proxy requires a stiff learning curve, and your use case does not require it.
The easier way is to copy the needed interface methods directly inside your contract(or some other class your contact will depend on, that will be open to the needed modifications). This way, you will be able to set your name and symbol whenever you want, and your contract will still be compliant with NFT interface. I know it looks like copying code is a bad idea, but you won't be able to change anything in your contract as soon as it is deployed(if it is not upgradable) thus, copying of the code doesn't matter in the long run.
To link another class, I can use [[package.Classname]].
Linking functions defined by def works as well, but trying to link variables doesn't work.
What I've tried:
object Foo {
val BAR = 0
}
object Example {
/**
* Does the thing with [[Foo.BAR]]
*/
def doTheThing(): Unit = {
}
}
I've also tried [[Foo#BAR]] (from another post) instead of [[Foo.BAR]], which fails as well.
What's the proper way to link variables in scaladoc?
The right way to go is what you have already tried:
/**
* Does the thing with [[Foo.BAR]]
*/
Please note that if this is just an example to a more complicated scenario, you need to include the whole package path of Foo.BAR. For example, if Foo is under:
package a.b.c.d
Then you need to do:
/**
* Does the thing with [[a.b.c.d.Foo.BAR]]
*/
You can find in the scaladocs docs:
Create links to referenced Scala Library classes using the square-bracket syntax, e.g. [[scala.Option]]
For more information you can read SCALADOC FOR LIBRARY AUTHORS
You can see here and example how the akka library is using it.
I have a project which contains several interface to other programs. These interfaces are defined as classes and spread out over the project.
I wonder whether it is possible that I can set a marker in the class description and doxygen later generates a list of links to all the markers.
e.g:
/** \marker interface **/
class Interface_01
{
}
/** \marker interface **/
class Interface_02
{
}
In a different doxygen file:
\listmarker interface
Which should then lead to something like this in the output:
* Interface_01
* Interface_02
This problem looks a bit like a problem for \xrefitem.
In the documentation:
the paragraph Aliases with arguments (http://doxygen.nl/manual/custcmd.html#custcmd_complex).
the command \xrefitem (http://doxygen.nl/manual/commands.html#cmdxrefitem)
Edit: This question is not off-topic as it describes an issue in data file handling with Turbo C++.
First of all, Turbo C++ is because of my school. Don't comment telling me to stop using it, I'm forced.
Introduction: I'm trying to build a DFH library, so I made all these functions to write, read, insert, delete, modify, etc.
I used stings to make the functions work for any filename passed to them.
What I understand (self-learned) from the whole making a class and then passing it's object in the read_stream.read((char*)& Object_1, sizeof(Object_1)); form to read the file, that you wrote using the same object is that: the class works as sort of a template to print data onto the file.
Question: I want to use them with different objects of different classes, so the class whose object these DFH functions use for performing the desired task should be sort of like a template.
I was thinking on doing something with templates or abstract class and inheritance but I'm a beginner so I need someone to point me in the right direction!
To clear up: I want to use the same functions by just including this source file into other programs containing different classes.
Example Code
class Data {
int user_id;
public:
void enter() { //Input Function
cout<<"\nID: ";
cin>>user_id;
};
void write(char* file_1) { //File Write Function
clrscr();
Data Object_1;
char ch;
int records_read =0;
ofstream fout;
fout.open(file_1, ios::binary|ios::noreplace);
do {
records_read++;
Object_1.enter(records_read);
fout.write((char*)& Object_1, sizeof(Object_1));
cout<<"\nDo you want to continue? Y/N - ";
cin>>ch;
} while((ch=='y')||(ch=='Y'));
cout<<"\nWrite Successful!";
fout.close();
}
How do I make the function write() work with any other class, without having to explicitly change the statement Data Object_1; ?
I'm working on Magento templates, but this issue would apply to any template loading system.
As these templates are loaded by the template engine there's no way for the IDE (in this case Aptana) to know what object type $this is.
Potentially it could more than one object as a single template could be loaded by multiple objects, but ignoring this, what would the correct phpdoc syntax be to specify a specific class for the $this object?
You can define it like this:
/* #var $this type */
where type is a class name
To be clear, using $this should only ever indicate an object of the current class, right?
PhpDocumentor doesn't currently (v1.4.3) recognize $this as a specific keyword that should equate to a datatype of the class itself.
Only datatypes known by PHP and classes already parsed by PhpDocumentor are the proper datatype values to use with the #return tag. There is a feature request in to have some option available in PhpDocumtentor to aid in documenting fluent methods that always "return $this". [1]
In the case of the #var tag, I don't see how it would be feasible for a class variable to contain its own class instance. As such, I can't follow what "#var $this" should be saying.
If, however, your intention with $this is not for fluent methods that "return $this", and was simply to be some shortcut to PhpDocumentor and/or your IDE to magically guess what datatypes you might mean by using $this, I'd have to guess there's no way to do it. The closest suggestion I could make would be to use the name of a parent class that is a common parent to all the various child classes that this particular var/return might be at runtime, and then use the description part of the tag to have inline {#link} tags that list out the possible child classes that are possible.
Example: I have a Parent abstract class with Child1, Child2, and Child3 children that each could occur in my runtime Foo class.
So, Foo::_var could be any of those child class types at runtime, but how would I document this?
/**
* #var Parent this could be any child of {#link Parent}, {#link Child1}, {#link Child2}, or {#link Child3}...
*/
protected $_var;
Getting back to the "return $this" issue, I'd document things in a similar way:
/**
* a fluent method (i.e. it returns this class's instance object)
* #return Parent this could be any child of {#link Parent}, {#link Child1}, {#link Child2}, or {#link Child3}...
*/
public function foo() {
return $this;
}
Documenting this way at least allows your class doc to have links to the particular classes. What it fails to do is highlight the fluent 'ness. However, if your IDE is capable of recognizing the class names, then perhaps it will be able to do the necessary logical linking to those other classes. I think Eclipse is able to do this at least with popup help, if you hover over the class name in the tag's description. I do not think Eclipse can use this to then make the various child classes' methods available in code completion. It would know about the Parent methods for code completion, because the datatype I explicitly list is Parent, but that's as far as the IDE can go.
[1] -- http://pear.php.net/bugs/bug.php?id=16223
I have found that defining a type with #var for $this does not work - presumably because $this is special and is treated as such by Aptana. I have a similar need to the poster I think - it is in template files (in my case simply located and included by functions within the data class) that I wish to set a type for $this. As #ashnazg says, setting a type for $this within a class definition is not needed, because the type of $this is always the type of the class (up to inheritance).
There is, however, a workaround for template files. At the top of the template file simply put something like
/**
* #var My_Data_Model_Type
*/
$dataModel = &$this;
Then simply use $dataModel (or whatever you choose to call it - maybe something shorter) instead of $this in the template