I have succeeded in creating a docset for my custom Cocoa Touch Static Library project using Doxygen. I can place links to other classes and members within the scope of my library project, but I cannot find a way to make (clickable) references to other frameworks, especially UIKit or NSFoundation.
This is an example of my documentation comments:
/**
If #shouldLoadDataFromTableEntriesJSONFile returns YES, this method
will be asked to provide the full path to the appropriate JSON file.
#return an absolute path to a JSON file.
#see MyOtherClass#aMethodThere
#see NSBundle#mainBundle
*/
Doxygen correctly creates a hyperlink to the shouldLoadDataFromTableEntriesJSONFile within that same class and to aMethodThere in MyOtherClass, but not to NSBundle#mainBundle. I understand that this might be more difficult, because it is located elsewhere, but can I set it up in a way to tell it how to do this?
Any special flags or variable defintions required that I am missing or is it merely a question of how to formulate it in the doc comments?
I just saw this (I had the same question). I have a not so ideal answer which might help: Linking to Apple (or 3rd party) documentation tokens in a docset
Related
I'm working on a open source project, which consist on a framework for iOS devices, and one of the methods is not working as I expected. I tried to search for the implementation of the method, but all I found was a a header file and the method declaration; I didn't find the implementation anywhere. Neither did I find the .m file corresponding to that class.
So I have some questions:
How can a class exist without it's implementation and still its methods perform certain operations?
What is the purpose of writing this kind of classes.
In this kind of situations where should be the methods implemented?
Note
The open source project is FastPdfKit and the method is wholeTextForPage:
Well, those methods are somewhere, so it's not that they don't exist, you just can't see them.
Try for example to open UITableView.h, you can see the methods definition, but not the implementation. The implementation is hidden in the library, but you can't see it.
In a nutshell, developers do this to hide the details of the implementation of a class to other users. You just receive a header that tells you which methods you can use, and how, but the details about how are they implemented are hidden for you.
For example, Apple doesn't want you to see how they implemented UITableView, but they want you to know how you can use it.
Here you can find a tutorial about how to create a library for Objective-C:
Creating Static Libraries for Objective-C
I'm just learning objective-c after a fair amount of experience with C#. One of the things I sorely miss is the ability to write extension methods in a separate project that I could reference in all of my projects. Here's some naive c#:
public static bool IsShortString(this string s) {
return s.length <= 3;
}
In Visual Studio, I could just add a reference, an using, and bam myString.IsShortString() would be a, rather useless, method.
So I think I want to write a static library, but I'm not sure where I'm going from there.
One additional question, if I do write this static library, will I be able to use all of the methods throughout various files in the library using one #import directive, or will I have to import each header individually?
What you are looking for is called Category, and it allows you to add some additional methods to existing classes. Check the reference http://developer.apple.com/library/ios/#documentation/cocoa/conceptual/objectivec/chapters/occategories.html
You can create your own toolkit which is a static library containing categories you made. Common practice is to create one header file containing imports for all the headers in the lib, so when using it, you just do
#import "libName.h"
Also, when creating a static library containing categories it is important to include -all_load and -ObjC linker flags to your project.
The closest thing in objective-c is categories.
This is also a good tutorial on categories.
This guy came up with a pretty neat tool to generate a class dependency graph - however, it relies on parsing your source code and looking for #import directives.
http://seriot.ch/blog.php?article=20110124
https://github.com/nst/objc_dep/blob/master/objc-dep.py
This is neat, but I have a number of problems with this. Not least of which is it doesn't take into account imports of imports nor prefix headers nor whether-or-not the class(es) in the file referenced by the import are actually being used.
I'd like to do something more akin to class-dump and examine the Objective-C metadata stored in the Mach-O file to generate an in-memory representation of the class dependencies.
I'd rather not do this from scratch, so I'm wondering:
Has it already been done?
Is there an open-source library which would provide me with the foundational tools I need to extract this information (a library which examines the Mach-O file and creates a façade of the Objective-C information contained within - such that I could iterate over all of the classes, their methods, properties, ivars, etc and scan for references to other classes) I figure class-dump's source would be a good place to start.
If you have experience in this sort of thing, is what I'm trying to accomplish feasible?
What roadblocks will I need to overcome?
Has it already been done?
Not that I know of.
Is there an open-source library which would provide me with the
foundational tools I need to extract this information?
At the core of class-dump is libMachObjC which does exatly what you want, i.e. parse all classes/methods/ivars and more. The API is very clean, it should be very easy to use.
If you have experience in this sort of thing, is what I'm trying to
accomplish feasible?
Unfortunately, no because some classes don't declare the real class but use id instead. For example, here is the information that can be extracted from a class-dump of UIKit:
#interface UITableView : UIScrollView <NSCoding>
{
int _style;
id <UITableViewDataSource> _dataSource;
id _rowData;
...
The _rowData ivar type information is id but if you check at runtime you will see that _rowData is an instance of the UITableViewRowData class. This information is not present in the Mach-O binary so you have no way to find the relation between UITableView and UITableViewRowData. The same applies for method parameters.
Here's a solution that relies on information in mach.o files, and generates graph dependency based on that information: https://github.com/PaulTaykalo/objc-dependency-visualizer
Has it already been done?
yes - but i can't recommend a good public implementation
Is there an open-source library which would provide me with the foundational tools I need to extract this information (a library which examines the Mach-O file and creates a façade of the Objective-C information contained within - such that I could iterate over all of the classes, their methods, properties, ivars, etc and scan for references to other classes) I figure class-dump's source would be a good place to start.
most use cases would benefit by using the objc runtime facilities objc/... rather than examining the binary.
If you have experience in this sort of thing, is what I'm trying to accomplish feasible?
yes. i've done something similar using the objc runtime.
What roadblocks will I need to overcome?
that depends largely on the level of detail you want... implementation time if you find no such implementation, but i figure you will find a few options if you google the more esoteric functions in the objc runtime; perhaps you would find one in an (open) language binding or bridge?
if you do end up writing one yourself, you can get registered objc classes using objc_getClassList, then access the properties/information you want from there.
I am creating a COM library with Embarcadero C++ Builder. The designer for the ridl file gives several things you can add to the ridl. I think I understand all of them except for creating new "Modules". I can't find good information for it in the documentation.
What is a "Module" and what would it be used for in COM?
You say you can't find 'good information' in the documentation; what have you found? The RAD Studio help has a section specifically explaining modules, which says:
A module defines a group of functions,
typically a set of DLL entry points.
You define a module by
Specifying a DLL that it represents on the attributes page.
Adding methods and constants using the toolbar or the object list pane
context menu. For each method or
constant, you must then define its
attributes by selecting the it in the
object list pane and setting the
values on the Attributes page.
For module methods, you must assign a
name and DLL entry point using the
attributes page. Declare the
function's parameters and return type
using the parameters page.
For module constants, use the
Attributes page to specify a name,
type, and value.
Note: The Type Library Editor does not generate any declarations or
implementation related to a module.
The specified DLL must be created as a
separate project.
It seems it's specifying methods that exist in an external DLL to whatever module (EXE or DLL) the type library is built into. Exactly what that's used for... is a good question.
The module attribute is described in this MSDN Library page. It permits declaring entrypoints in a DLL. That has little to do with COM, it is just a capability of a type library. You'll find few language development environments that can use them. I think VB6 was one of them. Ymmv.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
The common sense tells that the Doxygen comment blocks have to be put in the header files where the classes, structs, enums, functions, declarations are. I agree that this is a sound argument for a libraries that are mean to be distributed without its source (only headers and libs with object code).
BUT...I've been thinking of the exact opposite approach when I'm developing an internal to the company (or as a side project for myself) library that will be used with its full source code. What I propose is to put the large comment blocks in the implementations files (HPP, INL, CPP, etc) in order NOT to clutter the inteface of the classes and functions declared in the header.
Pros:
Less clutter in the header files, only categorizing of the functions can be added.
The comment blocks that are previewed when Intellisense for example is used doesn't clash - this is a defect that I have observed when I have a comment block for a function in the .H file and have its inline definition in the same .H file but included from .INL file.
Cons:
(The obvious one) The comment blocks are not in the header files where the declarations are.
So, what do you think and possibly suggest?
I like to make use of the fact that names can be documented in multiple places.
In the header file, I write a brief description of the method, and document all its parameters - these are less likely to change than the implementation of the method itself, and if they do, then the function prototype needs to be changed in any case.
I put long-format documentation in the source files next to the actual implementation, so the details can be changed as the method evolves.
For example:
mymodule.h
/// #brief This method adds two integers.
/// #param a First integer to add.
/// #param b Second integer to add.
/// #return The sum of both parameters.
int add(int a, int b);
mymodule.cpp
/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// #TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
return b + a;
}
Put the documentation where people will read and write it as they are using and working on the code.
Class comments go in front of classes, method comments in front of methods.
That is the best way to make sure things are maintained. It also keeps your header files relatively lean and avoids the touching issue of people updating method docs causing headers to be dirty and triggering rebuilds. I have actually known people use that as an excuse for writing documentation later!
Having comments in the header means that all users of a class must be recompiled if a comment is changed. For a large projects, coders will be less inclined to update comments in headers if they risk spending the next 20min rebuilding everything.
And.. since you're supposed to read the html doc and not browse through the code for documentation, it's not a large problem that the comment blocks are more difficult to locate in the source files.
Headers:
Easier to read the comments since there is less other "noise" when looking at the files.
Source:
Then you have the actual functions available for reading while looking at the comments.
We just use all global functions commented in headers and local functions commented in source. If you want you can also include the copydoc command to insert the documentation in multiple places without having to write it several times ( better for maintenance )
You could however also get the results copied over to different file documentation with a simple command. E.g. :-
My file1.h
/**
* \brief Short about function
*
* More about function
*/
WORD my_fync1(BYTE*);
MY file1.c
/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}
Now you get the same documentation on both functions.
This gives you less noise in the code files at the same time you get the documentation written in one place presented in several places in the final output.
I'm using QtCreator for programming. A very useful trick consists in Ctrl-Clicking on a function or method to get the declaration in the header file.
When the method is commented in the header file, you can quickly find the information you are looking for. So for me, comments should be located in the header file!
Usually I put documentation for interface (\param, \return) in .h file and documentation for implementation (\details) in .c/.cpp/.m file. Doxygen groups everything in the function/method documentation.
I put everything in the header file.
I document everything, but only generally extract the public interface.
In c++ sometimes implementation can be split between header and .cpp modules. Here it seems cleaner to put it documentation into the header file as that is the only place that all public functions and methods are guaranteed.