Revision: 4120
http://skim-app.svn.sourceforge.net/skim-app/?rev=4120&view=rev
Author: hofman
Date: 2008-07-02 15:24:57 -0700 (Wed, 02 Jul 2008)
Log Message:
-----------
Extend documentation tags.
Modified Paths:
--------------
trunk/SkimNotes/NSFileManager_SKNExtensions.h
trunk/SkimNotes/PDFAnnotation_SKNExtensions.h
trunk/SkimNotes/PDFDocument_SKNExtensions.h
trunk/SkimNotes/SKNExtendedAttributeManager.h
trunk/SkimNotes/SKNPDFAnnotationNote.h
Modified: trunk/SkimNotes/NSFileManager_SKNExtensions.h
===================================================================
--- trunk/SkimNotes/NSFileManager_SKNExtensions.h 2008-07-02 19:25:14 UTC
(rev 4119)
+++ trunk/SkimNotes/NSFileManager_SKNExtensions.h 2008-07-02 22:24:57 UTC
(rev 4120)
@@ -38,7 +38,7 @@
/*!
@header NSFileManager_SKNExtensions.h
- @discussion This file defines an NSFileManager category to read/write
Skim notes.
+ @discussion This file defines an <code>NSFileManager</code> category to
read/write Skim notes.
*/
#import <Cocoa/Cocoa.h>
@@ -55,18 +55,18 @@
@abstract Reads Skim notes as an array of property dictionaries from the
extended attributes of a file.
@discussion Reads the data from the extended attributes of the file and
convert.
@param aURL The URL for the file to read the Skim notes from.
- @param outError If there is an error reading the Skim notes, upon
return contains an NSError object that describes the problem.
- @result An array of dictionaries with Skim note properties, an empty
array if no Skim notes were found, or NULL if there was an error reading the
Skim notes.
+ @param outError If there is an error reading the Skim notes, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result An array of dictionaries with Skim note properties, an empty
array if no Skim notes were found, or <code>NULL</code> if there was an error
reading the Skim notes.
*/
- (NSArray *)readSkimNotesFromExtendedAttributesAtURL:(NSURL *)aURL
error:(NSError **)outError;
/*!
@method readSkimTextNotesFromExtendedAttributesAtURL:error:
@abstract Reads text Skim notes as a string from the extended attributes
of a file.
- @discussion Reads the data from the extended attributes of the file and
unarchives it using NSKeyedUnarchiver.
+ @discussion Reads the data from the extended attributes of the file and
unarchives it using <code>NSKeyedUnarchiver</code>.
@param aURL The URL for the file to read the text Skim notes from.
- @param outError If there is an error reading the text Skim notes,
upon return contains an NSError object that describes the problem.
- @result A string representation of the Skim notes, an empty string if
no text Skim notes were found, or NULL if there was an error reading the text
Skim notes.
+ @param outError If there is an error reading the text Skim notes,
upon return contains an <code>NSError</code> object that describes the problem.
+ @result A string representation of the Skim notes, an empty string if
no text Skim notes were found, or <code>NULL</code> if there was an error
reading the text Skim notes.
*/
- (NSString *)readSkimTextNotesFromExtendedAttributesAtURL:(NSURL *)aURL
error:(NSError **)outError;
@@ -75,8 +75,8 @@
@abstract Reads rich text Skim notes as RTF data from the extended
attributes of a file.
@discussion Reads the data from the extended attributes of the file.
@param aURL The URL for the file to read the RTF Skim notes from.
- @param outError If there is an error reading the RTF Skim notes, upon
return contains an NSError object that describes the problem.
- @result NSData for an RTF representation of the Skim notes, an empty
NSData object if no RTF Skim notes were found, or NULL if there was an error
reading the RTF Skim notes.
+ @param outError If there is an error reading the RTF Skim notes, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result <code>NSData</code> for an RTF representation of the Skim
notes, an empty <code>NSData</code> object if no RTF Skim notes were found, or
<code>NULL</code> if there was an error reading the RTF Skim notes.
*/
- (NSData *)readSkimRTFNotesFromExtendedAttributesAtURL:(NSURL *)aURL
error:(NSError **)outError;
@@ -86,7 +86,7 @@
@discussion Reads the data from a bundled file in the PDF bundle with the
proper .skim extension.
@param aURL The URL for the PDF bundle to read the Skim notes from.
@param outError If there is an error reading the Skim notes, upon
return contains an NSError object that describes the problem.
- @result An array of dictionaries with Skim note properties, an empty
array if no Skim notes were found, or NULL if there was an error reading the
Skim notes.
+ @result An array of dictionaries with Skim note properties, an empty
array if no Skim notes were found, or <code>NULL</code> if there was an error
reading the Skim notes.
*/
- (NSArray *)readSkimNotesFromPDFBundleAtURL:(NSURL *)aURL error:(NSError
**)outError;
@@ -95,8 +95,8 @@
@abstract Reads text Skim notes as a string from the contents of a PDF
bundle.
@discussion Reads the data from a bundled file in the PDF bundle with the
proper .txt extension.
@param aURL The URL for the PDF bundle to read the text Skim notes
from.
- @param outError If there is an error reading the text Skim notes,
upon return contains an NSError object that describes the problem.
- @result A string representation of the Skim notes, an empty string if
no text Skim notes were found, or NULL if there was an error reading the text
Skim notes.
+ @param outError If there is an error reading the text Skim notes,
upon return contains an <code>NSError</code> object that describes the problem.
+ @result A string representation of the Skim notes, an empty string if
no text Skim notes were found, or <code>NULL</code> if there was an error
reading the text Skim notes.
*/
- (NSString *)readSkimTextNotesFromPDFBundleAtURL:(NSURL *)aURL error:(NSError
**)outError;
@@ -105,8 +105,8 @@
@abstract Reads rich text Skim notes as RTF data from the contents of a
PDF bundle.
@discussion Reads the data from a bundled file in the PDF bundle with the
proper .rtf extension.
@param aURL The URL for the PDF bundle to read the RTF Skim notes
from.
- @param outError If there is an error reading the RTF Skim notes, upon
return contains an NSError object that describes the problem.
- @result NSData for an RTF representation of the Skim notes, an empty
NSData object if no RTF Skim notes were found, or NULL if there was an error
reading the RTF Skim notes.
+ @param outError If there is an error reading the RTF Skim notes, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result <code>NSData</code> for an RTF representation of the Skim
notes, an empty <code>NSData</code> object if no RTF Skim notes were found, or
<code>NULL</code> if there was an error reading the RTF Skim notes.
*/
- (NSData *)readSkimRTFNotesFromPDFBundleAtURL:(NSURL *)aURL error:(NSError
**)outError;
@@ -115,43 +115,43 @@
@abstract Reads Skim notes as an array of property dictionaries from the
contents of a .skim file.
@discussion Reads data from the file and unarchives it using
NSKeyedUnarchiver.
@param aURL The URL for the .skim file to read the Skim notes from.
- @param outError If there is an error reading the Skim notes, upon
return contains an NSError object that describes the problem.
- @result An array of dictionaries with Skim note properties, an empty
array if no Skim notes were found, or NULL if there was an error reading the
Skim notes.
+ @param outError If there is an error reading the Skim notes, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result An array of dictionaries with Skim note properties, an empty
array if no Skim notes were found, or <code>NULL</code> if there was an error
reading the Skim notes.
*/
- (NSArray *)readSkimNotesFromSkimFileAtURL:(NSURL *)aURL error:(NSError
**)outError;
/*!
@method writeSkimNotes:toExtendedAttributesAtURL:error:
- @abstract Writes Skim notes passed as an array of property dictionaries
to the extended attributes of a file, as well as a defaultrepresentation for
text Skim notes and RTF Skim notes.
- @discussion Calls
writeSkimNotes:textNotes:richTextNotes:toExtendedAttributesAtURL:error: with
nil notesString and notesRTFData.
+ @abstract Writes Skim notes passed as an array of property dictionaries
to the extended attributes of a file, as well as a defaultrepresentation for
text Skim notes and RTF Skim notes.
+ @discussion Calls
<code>writeSkimNotes:textNotes:richTextNotes:toExtendedAttributesAtURL:error:</code>
with nil <code>notesString</code> and <code>notesRTFData</code>.
@param notes An array of dictionaries containing Skim note
properties, as returned by the properties of a PDFAnnotation.
@param aURL The URL for the file to write the Skim notes to.
- @param outError If there is an error writing the Skim notes, upon
return contains an NSError object that describes the problem.
- @result Returns YES if writing out the Skim notes was successful;
otherwise returns NO.
+ @param outError If there is an error writing the Skim notes, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result Returns <code>YES</code> if writing out the Skim notes was
successful; otherwise returns <code>NO</code>.
*/
- (BOOL)writeSkimNotes:(NSArray *)notes toExtendedAttributesAtURL:(NSURL
*)aURL error:(NSError **)outError;
/*!
@method
writeSkimNotes:textNotes:richTextNotes:toExtendedAttributesAtURL:error:
- @abstract Writes Skim notes passed as an array of property dictionaries
to the extended attributes of a file, as well as text Skim notes and RTF Skim
notes. The array is converted to NSData using NSKeyedArchiver.
- @discussion This writes three types of Skim notes to the extended
attributes to the file located through aURL.
- @param notes An array of dictionaries containing Skim note
properties, as returned by the properties of a PDFAnnotation.
- @param notesString A text representation of the Skim notes. When
NULL, a default representation will be generated from notes.
- @param notesRTFData An RTF data representation of the Skim notes.
When NULL, a default representation will be generated from notes.
+ @abstract Writes Skim notes passed as an array of property dictionaries
to the extended attributes of a file, as well as text Skim notes and RTF Skim
notes. The array is converted to <code>NSData</code> using
<code>NSKeyedArchiver</code>.
+ @discussion This writes three types of Skim notes to the extended
attributes to the file located through <code>aURL</code>.
+ @param notes An array of dictionaries containing Skim note
properties, as returned by the properties of a <code>PDFAnnotation</code>.
+ @param notesString A text representation of the Skim notes. When
<code>NULL</code>, a default representation will be generated from notes.
+ @param notesRTFData An RTF data representation of the Skim notes.
When <code>NULL</code>, a default representation will be generated from notes.
@param aURL The URL for the file to write the Skim notes to.
- @param outError If there is an error writing the Skim notes, upon
return contains an NSError object that describes the problem.
- @result Returns YES if writing out the Skim notes was successful;
otherwise returns NO.
+ @param outError If there is an error writing the Skim notes, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result Returns <code>YES</code> if writing out the Skim notes was
successful; otherwise returns <code>NO</code>.
*/
- (BOOL)writeSkimNotes:(NSArray *)notes textNotes:(NSString *)notesString
richTextNotes:(NSData *)notesRTFData toExtendedAttributesAtURL:(NSURL *)aURL
error:(NSError **)outError;
/*!
@method writeSkimNotes:toSkimFileAtURL:error:
@abstract Writes Skim notes passed as an array of property dictionaries
to a .skim file.
- @discussion Archives notes using NSKeyedArchiver and writes the data to
the file located by aURL.
- @param notes An array of dictionaries containing Skim note
properties, as returned by the properties of a PDFAnnotation.
+ @discussion Archives notes using NSKeyedArchiver and writes the data to
the file located by <code>aURL</code>.
+ @param notes An array of dictionaries containing Skim note
properties, as returned by the properties of a <code>PDFAnnotation</code>.
@param aURL The URL for the .skim file to write the Skim notes to.
- @param outError If there is an error writing the Skim notes, upon
return contains an NSError object that describes the problem.
- @result Returns YES if writing out the Skim notes was successful;
otherwise returns NO.
+ @param outError If there is an error writing the Skim notes, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result Returns <code>YES</code> if writing out the Skim notes was
successful; otherwise returns <code>NO</code>.
*/
- (BOOL)writeSkimNotes:(NSArray *)notes toSkimFileAtURL:(NSURL *)aURL
error:(NSError **)outError;
@@ -161,8 +161,8 @@
@discussion If more than one bundled files with the given extension exist
in the PDF bundle, this will follow the naming rules followed by Skim to find
the best match.
@param extension The file extension for which to find a bundled file.
@param path The path to the PDF bundle.
- @param outError If there is an error getting the bundled file, upon
return contains an NSError object that describes the problem.
- @result A full path to the bundled file inside the PDF bundle, or NULL
if no bundled file was found.
+ @param outError If there is an error getting the bundled file, upon
return contains an <code>NSError</code> object that describes the problem.
+ @result A full path to the bundled file inside the PDF bundle, or
<code>NULL</code> if no bundled file was found.
*/
- (NSString *)bundledFileWithExtension:(NSString *)extension
inPDFBundleAtPath:(NSString *)path error:(NSError **)outError;
Modified: trunk/SkimNotes/PDFAnnotation_SKNExtensions.h
===================================================================
--- trunk/SkimNotes/PDFAnnotation_SKNExtensions.h 2008-07-02 19:25:14 UTC
(rev 4119)
+++ trunk/SkimNotes/PDFAnnotation_SKNExtensions.h 2008-07-02 22:24:57 UTC
(rev 4120)
@@ -38,7 +38,7 @@
/*!
@header PDFAnnotation_SKNExtensions.h
- @discussion This file defines an PDFAnnotation categories to manage Skim
notes.
+ @discussion This file defines an <code>PDFAnnotation</code> categories to
manage Skim notes.
*/
#import <Cocoa/Cocoa.h>
#import <Quartz/Quartz.h>
@@ -86,8 +86,8 @@
/*!
@category PDFAnnotation (SKNExtensions)
- @abstract Provides methods to translate between dictionary
representations of Skim notes and PDFAnnotation objects.
- @discussion Methods from this category are used by the PDFDocument
(SKNExtensions) category to add new annotations from Skim notes.
+ @abstract Provides methods to translate between dictionary
representations of Skim notes and <code>PDFAnnotation</code> objects.
+ @discussion Methods from this category are used by the <code>PDFDocument
(SKNExtensions)</code> category to add new annotations from Skim notes.
*/
@interface PDFAnnotation (SKNExtensions)
@@ -96,16 +96,16 @@
@abstract Initializes a new Skim note annotation. This is the
designated initializer for a Skim note.
@discussion This method can be implemented in subclasses to provide
default properties for Skim notes.
@param bounds The bounding box of the annotation, in page space.
- @result An initialized Skim note annotation instance, or NULL if the
object could not be initialized.
+ @result An initialized Skim note annotation instance, or
<code>NULL</code> if the object could not be initialized.
*/
- (id)initSkimNoteWithBounds:(NSRect)bounds;
/*!
@method initSkimNoteWithProperties:
@abstract Initializes a new Skim note annotation with the given
properties.
- @discussion This method determines the proper subclass from the value for
the "type" key in dict, initializes an instance using initSkimNoteWithBounds:,
and sets the known properties from dict. Implementations in subclasses should
call it on super and set their properties from dict if available.
- @param dict A dictionary with Skim notes properties, as returned from
properties. This is required to contain values for "type" and "bounds".
- @result An initialized Skim note annotation instance, or NULL if the
object could not be initialized.
+ @discussion This method determines the proper subclass from the value for
the <code>"type"</code> key in dict, initializes an instance using
<code>initSkimNoteWithBounds:</code>, and sets the known properties from dict.
Implementations in subclasses should call it on super and set their properties
from dict if available.
+ @param dict A dictionary with Skim notes properties, as returned from
properties. This is required to contain values for <code>"type"</code> and
<code>"bounds"</code>.
+ @result An initialized Skim note annotation instance, or
<code>NULL</code> if the object could not be initialized.
*/
- (id)initSkimNoteWithProperties:(NSDictionary *)dict;
@@ -113,14 +113,14 @@
@method properties
@abstract The Skim notes properties.
@discussion These properties can be used to initialize a new copy, and to
save to extended attributes or file.
- @result A dictionary with properties of the Skim note. All values are
standard Cocoa objects conforming to NSCoding and NSCopying.
+ @result A dictionary with properties of the Skim note. All values are
standard Cocoa objects conforming to <code>NSCoding</code> and
<code>NSCopying</code>.
*/
- (NSDictionary *)properties;
/*!
@method isSkimNote
@abstract Returns whether the annotation is a Skim note.
- @discussion An annotation initalized with initializers starting with
initSkimNote will return YES by default.
+ @discussion An annotation initalized with initializers starting with
initSkimNote will return <code>YES</code> by default.
@result YES if the annotation is a Skim note; otherwise NO.
*/
- (BOOL)isSkimNote;
@@ -128,15 +128,15 @@
/*!
@method setSkimNote:
@abstract Sets whether the receiver is to be interpreted as a Skim note.
- @discussion You normally would not use this yourself, but rely on the
initializer to set the isSkimNote flag.
- @param flag Set this value to YES if you want the annotation to be
interpreted as a Skim note.
+ @discussion You normally would not use this yourself, but rely on the
initializer to set the <code>isSkimNote</code> flag.
+ @param flag Set this value to <code>YES</code> if you want the
annotation to be interpreted as a Skim note.
*/
- (void)setSkimNote:(BOOL)flag;
/*!
@method string
@abstract The string value of the annotation.
- @discussion By default, this is just the same as the contents. However
for SKNPDFAnnotationNote the contents will contain both string and text.
+ @discussion By default, this is just the same as the contents. However
for <code>SKNPDFAnnotationNote</code> the contents will contain both string and
text.
@result A string representing the string value associated with the
annotation.
*/
- (NSString *)string;
@@ -144,7 +144,7 @@
/*!
@method setString:
@abstract Sets the string of the annotation. By default just sets the
contents.
- @discussion By default just calls setContent:.
+ @discussion By default just calls <code>setContent:</code>.
@param newString The new string value for the annotation.
*/
- (void)setString:(NSString *)newString;
@@ -155,8 +155,8 @@
/*!
@category PDFAnnotationCircle (SKNExtensions)
- @abstract Provides methods to translate between dictionary
representations of Skim notes and PDFAnnotation objects.
- @discussion Implements initSkimNotesWithProperties: and properties to
take care of the extra properties of a circle annotation.
+ @abstract Provides methods to translate between dictionary
representations of Skim notes and <code>PDFAnnotation</code> objects.
+ @discussion Implements <code>initSkimNotesWithProperties:</code> and
properties to take care of the extra properties of a circle annotation.
*/
@interface PDFAnnotationCircle (SKNExtensions)
@end
@@ -165,8 +165,8 @@
/*!
@category PDFAnnotationSquare (SKNExtensions)
- @abstract Provides methods to translate between dictionary
representations of Skim notes and PDFAnnotation objects.
- @discussion Implements initSkimNotesWithProperties: and properties to
take care of the extra properties of a square annotation.
+ @abstract Provides methods to translate between dictionary
representations of Skim notes and <code>PDFAnnotation</code> objects.
+ @discussion Implements <code>initSkimNotesWithProperties:</code> and
properties to take care of the extra properties of a square annotation.
*/
@interface PDFAnnotationSquare (SKNExtensions)
@end
@@ -175,8 +175,8 @@
/*!
@category PDFAnnotationLine (SKNExtensions)
- @abstract Provides methods to translate between dictionary
representations of Skim notes and PDFAnnotation objects.
- @discussion Implements initSkimNotesWithProperties: and properties to
take care of the extra properties of a line annotation.
+ @abstract Provides methods to translate between dictionary
representations of Skim notes and <code>PDFAnnotation</code> objects.
+ @discussion Implements <code>initSkimNotesWithProperties:</code> and
properties to take care of the extra properties of a line annotation.
*/
@interface PDFAnnotationLine (SKNExtensions)
@end
@@ -185,8 +185,8 @@
/*!
@category PDFAnnotationFreeText (SKNExtensions)
- @abstract Provides methods to translate between dictionary
representations of Skim notes and PDFAnnotation objects.
- @discussion Implements initSkimNotesWithProperties: and properties to
take care of the extra properties of a free text annotation.
+ @abstract Provides methods to translate between dictionary
representations of Skim notes and <code>PDFAnnotation</code> objects.
+ @discussion Implements <code>initSkimNotesWithProperties:</code> and
properties to take care of the extra properties of a free text annotation.
*/
@interface PDFAnnotationFreeText (SKNExtensions)
@end
@@ -195,8 +195,8 @@
/*!
@category PDFAnnotationMarkup (SKNExtensions)
- @abstract Provides methods to translate between dictionary
representations of Skim notes and PDFAnnotation objects.
- @discussion Implements initSkimNotesWithProperties: and properties to
take care of the extra properties of a markup annotation.
+ @abstract Provides methods to translate between dictionary
representations of Skim notes and <code>PDFAnnotation</code> objects.
+ @discussion Implements <code>initSkimNotesWithProperties:</code> and
properties to take care of the extra properties of a markup annotation.
*/
@interface PDFAnnotationMarkup (SKNExtensions)
@end
@@ -204,7 +204,7 @@
/*!
@category PDFAnnotationMarkup (SKNOptional)
@abstract An informal protocol providing a method name for an optional
method that may be implemented in a category.
- @discussion This defines an optional method that another
PDFAnnotationMarkup category may implement to provide a default color.
+ @discussion This defines an optional method that another
<code>PDFAnnotationMarkup</code> category may implement to provide a default
color.
*/
@interface PDFAnnotationMarkup (SKNOptional)
/*!
@@ -221,8 +221,8 @@
/*!
@category PDFAnnotationText (SKNExtensions)
- @abstract Provides methods to translate between dictionary
representations of Skim notes and PDFAnnotation objects.
- @discussion Implements initSkimNotesWithProperties: and properties to
take care of the extra properties of a text annotation.
+ @abstract Provides methods to translate between dictionary
representations of Skim notes and <code>PDFAnnotation</code> objects.
+ @discussion Implements <code>initSkimNotesWithProperties:</code> and
properties to take care of the extra properties of a text annotation.
*/
@interface PDFAnnotationText (SKNExtensions)
@end
Modified: trunk/SkimNotes/PDFDocument_SKNExtensions.h
===================================================================
--- trunk/SkimNotes/PDFDocument_SKNExtensions.h 2008-07-02 19:25:14 UTC (rev
4119)
+++ trunk/SkimNotes/PDFDocument_SKNExtensions.h 2008-07-02 22:24:57 UTC (rev
4120)
@@ -38,7 +38,7 @@
/*!
@header PDFDocument_SKNExtensions.h
- @discussion This file defines an PDFDocument category to add Skim note
annotations to a PDFDocument.
+ @discussion This file defines an <code>PDFDocument</code> category to add
Skim note annotations to a <code>PDFDocument</code>.
*/
#import <Cocoa/Cocoa.h>
#import <Quartz/Quartz.h>
@@ -46,27 +46,27 @@
/*!
@category PDFDocument (SKNExtensions)
- @abstract Provides methods to add Skim notes to a PDFDocument.
- @discussion This category can be used to add Skim notes from their
properties to a PDFDocument or easily load a PDFDocument including attached
Skim notes.
+ @abstract Provides methods to add Skim notes to a
<code>PDFDocument</code>.
+ @discussion This category can be used to add Skim notes from their
properties to a <code>PDFDocument</code> or easily load a
<code>PDFDocument</code> including attached Skim notes.
*/
@interface PDFDocument (SKNExtensions)
/*!
@method initWithURL:readSkimNotes:
- @abstract Initializes a new PDFDocument from a file or PDF bundle,
adding Skim notes from the extended attributes of the file or the contents of
the PDF bundle. The added Skim notes are returned by reference as an array of
PDFAnnotations.
- @discussion Initializes a new PDFDocument using initWithURL:, reads Skim
notes from theextended attributes or the bundle, and adds new PDFAnnotation
objects to the document initialized by the found Skim note properties.
+ @abstract Initializes a new <code>PDFDocument</code> from a file or PDF
bundle, adding Skim notes from the extended attributes of the file or the
contents of the PDF bundle. The added Skim notes are returned by reference as
an array of <code>PDFAnnotation</code>s.
+ @discussion Initializes a new <code>PDFDocument</code> using
<code>initWithURL:</code>, reads Skim notes from theextended attributes or the
bundle, and adds new <code>PDFAnnotation</code> objects to the document
initialized by the found Skim note properties.
@param url The URL of the PDF file or PDF bundle.
- @param notes An array of PDFAnnotation objects initialized using the
Skim note properties read from the extended attributes or bundled Skim file.
- @result The initialized PDFDocument.
+ @param notes An array of <code>PDFAnnotation</code> objects
initialized using the Skim note properties read from the extended attributes or
bundled Skim file.
+ @result The initialized <code>PDFDocument</code>.
*/
- (id)initWithURL:(NSURL *)url readSkimNotes:(NSArray **)notes;
/*!
@method addSkimNotesWithProperties:
- @abstract Adds new Skim notes from an array of property dictionaries to
the receiver, and returns the added Skim notes as an array of PDFAnnotations.
- @discussion This method initializes new PDFAnnotation objects from the
passed in properties and adds them to the appropriate pages of the PDFDocument.
- @param noteDicts An array of dictionaries containing Skim note
properties as returned by the properties of PDFAnnotation objects.
- @result An array of PDFAnnotation objects initialized using the Skim
note properties read from the extended attributes or bundled Skim file.
+ @abstract Adds new Skim notes from an array of property dictionaries to
the receiver, and returns the added Skim notes as an array of
<code>PDFAnnotations</code>.
+ @discussion This method initializes new <code>PDFAnnotation</code> objects
from the passed in properties and adds them to the appropriate pages of the
<code>PDFDocument</code>.
+ @param noteDicts An array of dictionaries containing Skim note
properties as returned by the properties of <code>PDFAnnotation</code> objects.
+ @result An array of <code>PDFAnnotation</code> objects initialized
using the Skim note properties read from the extended attributes or bundled
Skim file.
*/
- (NSArray *)addSkimNotesWithProperties:(NSArray *)noteDicts;
Modified: trunk/SkimNotes/SKNExtendedAttributeManager.h
===================================================================
--- trunk/SkimNotes/SKNExtendedAttributeManager.h 2008-07-02 19:25:14 UTC
(rev 4119)
+++ trunk/SkimNotes/SKNExtendedAttributeManager.h 2008-07-02 22:24:57 UTC
(rev 4120)
@@ -34,19 +34,30 @@
*/
#import <Cocoa/Cocoa.h>
-typedef UInt32 SKNXattrFlags;
+/*!
+ @enum SKNXattrFlags
+ @abstract Options for writing extended attributes.
+ @discussion These options can be passed to methods writing extended
attributes to modify the way these methods behave.
+ @constant kSKNXattrDefault Create or replace, follow symlinks,
split data.
+ @constant kSKNXattrNoFollow Don't follow symlinks.
+ @constant kSKNXattrCreateOnly Setting will fail if the attribute
already exists.
+ @constant kSKNXattrReplaceOnly Setting will fail if the attribute does
not exist.
+ @constant kSKNXattrNoSplitData Don't split data objects into segments.
+*/
enum {
- kSKNXattrDefault = 0, /* create or replace, follow symlinks,
split data */
- kSKNXattrNoFollow = 1L << 1, /* don't follow symlinks
*/
- kSKNXattrCreateOnly = 1L << 2, /* setting will fail if the attribute
already exists */
- kSKNXattrReplaceOnly = 1L << 3, /* setting will fail if the attribute does
not exist */
- kSKNXattrNoSplitData = 1L << 4 /* don't split data objects into segments
*/
+ kSKNXattrDefault = 0,
+ kSKNXattrNoFollow = 1L << 1,
+ kSKNXattrCreateOnly = 1L << 2,
+ kSKNXattrReplaceOnly = 1L << 3,
+ kSKNXattrNoSplitData = 1L << 4
};
+typedef UInt32 SKNXattrFlags;
+
/*!
@class SKNExtendedAttributeManager
@abstract Provides an Objective-C wrapper for the low-level BSD
functions dealing with file attributes.
- @discussion (comprehensive description)
+ @discussion This class is the core object to read and write extended
attributes, which are used to store Skim notes with PDF files.
*/
@interface SKNExtendedAttributeManager : NSObject {
NSString *namePrefix;
@@ -58,16 +69,17 @@
/*!
@method sharedManager
@abstract Returns the shared instance. You probably always should use
this instance, and is required for Skim notes.
- @discussion (comprehensive description)
- @result (description)
+ @discussion This shared manager uses the default prefix and is used for
reading and writing Skim notes to PDF files. It may split attributes into
fragments if the data is too long.
+ @result The default shared EA manager used for Skim notes.
*/
+ (id)sharedManager;
/*!
@method sharedNoSplitManager
@abstract Returns a shared instance with nil prefix. This instance
never splits attributes, and can also not reassemble splitted attributes.
- @discussion (comprehensive description)
- @result (description)
+ @discussion This manager never splits attributes into fragments. Settting
attributes is always as if <code>kSKNXattrNoSplitData</code> is passed. Also
when reading it will not be able to reassemble split attributes.
+ However attributes that were set using this manager will be
readable also by managers with different prefixes, such as the
<code>sharedManager</code>.
+ @result A shared EA manager that never splits extended attributes.
*/
+ (id)sharedNoSplitManager;
@@ -77,43 +89,44 @@
@discussion The prefix is used in splitting large attributes. EA managers
with different prefixes are mutually incompatible,
i.e. attributes written with one manager cannot be safely read
by a manager with a different prefix.
It is safest to just use the shared instance. The prefix
should only contain characters that are valid in attribute names.
- @param prefix Defaults to "net_sourceforge_skim-app" for the shared
instance. If nil, the manager never splits attributes.
- @result (description)
+ This is the designated initializer, and should be used for any
subclass.
+ @param prefix Defaults to <code>"net_sourceforge_skim-app"</code> for
the shared instance. If <code>nil</code>, the manager never splits attributes.
+ @result An initialized EA manager object. This may be one of the
shared managers.
*/
- (id)initWithPrefix:(NSString *)prefix;
/*!
@method extendedAttributeNamesAtPath:traverseLink:
@abstract Return a list of extended attributes for the given file.
- @discussion Calls <tt>listxattr(2)</tt> to determine all of the extended
attributes, and returns them as
- an array of NSString objects. Returns nil if an error occurs.
+ @discussion Calls <code>listxattr(2)</code> to determine all of the
extended attributes, and returns them as
+ an array of <code>NSString</code> objects. Returns
<code>nil</code> if an error occurs.
@param path Path to the object in the file system.
- @param follow Follow symlinks (<tt>listxattr(2)</tt> does this by
default, so typically you should pass YES).
- @param error Error object describing the error if nil was returned.
- @result Array of strings or nil.
+ @param follow Follow symlinks (<code>listxattr(2)</code> does this by
default, so typically you should pass <code>YES</code>).
+ @param error Error object describing the error if <code>nil</code>
was returned.
+ @result Array of strings or <code>nil</code> if an error occurred.
*/
- (NSArray *)extendedAttributeNamesAtPath:(NSString *)path
traverseLink:(BOOL)follow error:(NSError **)error;
/*!
@method extendedAttributeNamed:atPath:traverseLink:error:
- @abstract Return the extended attribute named <tt>attr</tt> for a given
file.
- @discussion Calls <tt>getxattr(2)</tt> to determine the extended
attribute, and returns it as data.
+ @abstract Return the extended attribute named <code>attr</code> for a
given file.
+ @discussion Calls <code>getxattr(2)</code> to determine the extended
attribute, and returns it as data.
@param attr The attribute name.
@param path Path to the object in the file system.
- @param follow Follow symlinks (<tt>getxattr(2)</tt> does this by
default, so typically you should pass YES).
- @param error Error object describing the error if nil was returned.
- @result Data object representing the extended attribute or nil if an
error occurred.
+ @param follow Follow symlinks (<code>getxattr(2)</code> does this by
default, so typically you should pass <code>YES</code>).
+ @param error Error object describing the error if <code>nil</code>
was returned.
+ @result Data object representing the extended attribute or
<code>nil</code> if an error occurred.
*/
- (NSData *)extendedAttributeNamed:(NSString *)attr atPath:(NSString *)path
traverseLink:(BOOL)follow error:(NSError **)error;
/*!
@method allExtendedAttributesAtPath:traverseLink:error:
- @abstract Returns all extended attributes for the given file, each as an
NSData object.
- @discussion (comprehensive description)
- @param path (description)
- @param follow (description)
- @param error (description)
- @result (description)
+ @abstract Returns all extended attributes for the given file, each as an
<code>NSData</code> object.
+ @discussion Calls
<code>extendedAttributeNamesAtPath:traverseLink:error:</code> to find all
attribute names and then calls
<code>extendedAttributeNamed:atPath:traverseLink:error:</code> repreatedly for
all attribute names.
+ @param path Path to the object in the file system.
+ @param follow Follow symlinks (<code>getxattr(2)</code> does this by
default, so typically you should pass <code>YES</code>).
+ @param error Error object describing the error if <code>nil</code>
was returned.
+ @result Array of data objects or <code>nil</code> if an error occurred.
*/
- (NSArray *)allExtendedAttributesAtPath:(NSString *)path
traverseLink:(BOOL)follow error:(NSError **)error;
@@ -121,60 +134,62 @@
@method
propertyListFromExtendedAttributeNamed:atPath:traverseLink:error:
@abstract Returns a property list using NSPropertyListSerialization.
@discussion (comprehensive description)
- @param attr (description)
- @param path (description)
- @param traverse (description)
- @param error (description)
- @result (description)
+ @param attr The attribute name.
+ @param path Path to the object in the file system.
+ @param follow Follow symlinks (<code>getxattr(2)</code> does this by
default, so typically you should pass <code>YES</code>).
+ @param error Error object describing the error if <code>nil</code>
was returned.
+ @result A property list object <code>nil</code> if an error occurred.
*/
-- (id)propertyListFromExtendedAttributeNamed:(NSString *)attr atPath:(NSString
*)path traverseLink:(BOOL)traverse error:(NSError **)error;
+- (id)propertyListFromExtendedAttributeNamed:(NSString *)attr atPath:(NSString
*)path traverseLink:(BOOL)follow error:(NSError **)error;
/*!
@method setExtendedAttributeNamed:toValue:atPath:options:error:
- @abstract Sets the value of attribute named <tt>attr</tt> to
<tt>value</tt>, which is an NSData object.
- @discussion Calls <tt>setxattr(2)</tt> to set the attributes for the file.
+ @abstract Sets the value of attribute named <code>attr</code> to
<code>value</code>, which is an <code>NSData</code> object.
+ @discussion Calls <code>setxattr(2)</code> to set the attributes for the
file.
+ If the options do not contain the
<code>kSKNXattrNoSplitData</code> flag and the prefix is not <code>nil</code>,
the data may be split into subfragments and a dictionary pointing to the
fragments is saved in the attribute names <code>attr</code>.
@param attr The attribute name.
- @param value The value of the attribute as NSData.
+ @param value The value of the attribute as <code>NSData</code>.
@param path Path to the object in the file system.
- @param options see SKNXattrFlags
- @param error Error object describing the error if NO was returned.
- @result Returns NO if an error occurred.
+ @param options See </code>SKNXattrFlags<code> for valid options and
their behavior.
+ @param error Error object describing the error if <code>NO</code> was
returned.
+ @result Returns <code>NO</code> if an error occurred.
*/
- (BOOL)setExtendedAttributeNamed:(NSString *)attr toValue:(NSData *)value
atPath:(NSString *)path options:(SKNXattrFlags)options error:(NSError **)error;
/*!
@method
setExtendedAttributeNamed:toPropertyListValue:atPath:options:error:
- @abstract Sets the extended attribute named <tt>attr</tt> to the
specified property list. The plist is converted to NSData using
NSPropertyListSerialization.
- @discussion (comprehensive description)
- @param attr (description)
- @param plist (description)
- @param path (description)
- @param options (description)
- @param error (description)
- @result (description)
+ @abstract Sets the extended attribute named <code>attr</code> to the
specified property list.
+ @discussion The plist is converted to <code>NSData</code> using
<code>NSPropertyListSerialization</code> and set using
<code>setExtendedAttributeNamed:toValue:atPath:options:error:</code>.
+ For the non-split manager without prefix, the data may be
compressed using <code>bzip2</code> when the archived data is too large.
+ @param attr The attribute name.
+ @param plist The value of the attribute as a plist object.
+ @param path Path to the object in the file system.
+ @param options See </code>SKNXattrFlags<code> for valid options and
their behavior.
+ @param error Error object describing the error if <code>NO</code> was
returned.
+ @result Returns <code>NO</code> if an error occurred.
*/
- (BOOL)setExtendedAttributeNamed:(NSString *)attr
toPropertyListValue:(id)plist atPath:(NSString *)path
options:(SKNXattrFlags)options error:(NSError **)error;
/*!
@method removeExtendedAttribute:atPath:followLinks:error:
- @abstract Removes the given attribute <tt>attr</tt> from the named file
at <tt>path</tt>.
- @discussion Calls <tt>removexattr(2)</tt> to remove the given attribute
from the file.
+ @abstract Removes the given attribute <code>attr</code> from the named
file at <code>path</code>.
+ @discussion Calls <code>removexattr(2)</code> to remove the given
attribute from the file.
@param attr The attribute name.
@param path Path to the object in the file system.
- @param follow Follow symlinks (<tt>removexattr(2)</tt> does this by
default, so typically you should pass YES).
- @param error Error object describing the error if nil was returned.
- @result Returns NO if an error occurred.
+ @param follow Follow symlinks (<code>removexattr(2)</code> does this
by default, so typically you should pass <code>YES</code>).
+ @param error Error object describing the error if <code>nil</code>
was returned.
+ @result Returns <code>NO</code> if an error occurred.
*/
- (BOOL)removeExtendedAttribute:(NSString *)attr atPath:(NSString *)path
traverseLink:(BOOL)follow error:(NSError **)error;
/*!
@method removeAllExtendedAttributesAtPath:traverseLink:error:
@abstract Removes all extended attributes at the specified path.
- @discussion (comprehensive description)
- @param path (description)
- @param follow (description)
- @param error (description)
- @result (description)
+ @discussion Calls <code>removexattr(2)</code> repeatedly to remove all
attributes from the file.
+ @param path Path to the object in the file system.
+ @param follow Follow symlinks (<code>removexattr(2)</code> does this
by default, so typically you should pass <code>YES</code>).
+ @param error Error object describing the error if <code>NO</code> was
returned.
+ @result Returns <code>NO</code> if an error occurred.
*/
- (BOOL)removeAllExtendedAttributesAtPath:(NSString *)path
traverseLink:(BOOL)follow error:(NSError **)error;
Modified: trunk/SkimNotes/SKNPDFAnnotationNote.h
===================================================================
--- trunk/SkimNotes/SKNPDFAnnotationNote.h 2008-07-02 19:25:14 UTC (rev
4119)
+++ trunk/SkimNotes/SKNPDFAnnotationNote.h 2008-07-02 22:24:57 UTC (rev
4120)
@@ -38,7 +38,7 @@
/*!
@header SKNPDFAnnotationNote.h
- @discussion This file defines a concrete PDFAnnotation class representing
a SKim anchored note.
+ @discussion This file defines a concrete <code>PDFAnnotation</code> class
representing a SKim anchored note.
*/
#import <Cocoa/Cocoa.h>
#import <Quartz/Quartz.h>
@@ -50,8 +50,8 @@
/*!
class SKNPDFAnnotationNote
- @abstract A concrete PDFAnnotation subclass, a subclass of
PDFAnnotationText, representing a Skim anchored note.
- @discussion This is a PDFAnnotationText subclass containing a separate
short string value, a longer rich text property, and an image property.
+ @abstract A concrete <code>PDFAnnotation</code> subclass, a subclass of
<code>PDFAnnotationText</code>, representing a Skim anchored note.
+ @discussion This is a <code>PDFAnnotationText</code> subclass containing
a separate short string value, a longer rich text property, and an image
property.
*/
@interface SKNPDFAnnotationNote : PDFAnnotationText {
NSString *string;
@@ -72,7 +72,7 @@
/*!
@method setString:
@abstract This is overridden and different from the contents.
- @discussion This should set the short string value of the annotation.
This updates the contents using updateContents.
+ @discussion This should set the short string value of the annotation.
This updates the contents using <code>updateContents</code>.
@param newString The new string value for the annotation.
*/
- (void)setString:(NSString *)newString;
@@ -87,7 +87,7 @@
/*!
@method setText:
@abstract Sets the rich text of the annotation.
- @discussion This should set the longer rich text contents of the
annotation. This updates the contents using updateContents.
+ @discussion This should set the longer rich text contents of the
annotation. This updates the contents using <code>updateContents</code>.
@param newText The new rich text value for the annotation.
*/
- (void)setText:(NSAttributedString *)newText;
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Skim-app-commit mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/skim-app-commit
