Merge pull request #7 from Peterkrol12/feature/public-member-documentation

Added documentation for public members

Author: Peterkrol12

example/main.dart

@@ -1,24 +1,31 @@
+import 'dart:developer';
 import 'dart:io';
 
 import 'package:http/io_client.dart';
-import 'package:webfeed_revised/webfeed.dart';
+import 'package:webfeed_revised/webfeed_revised.dart';
 
 void main() async {
-  final client = IOClient(HttpClient()
-    ..badCertificateCallback =
-        ((X509Certificate cert, String host, int port) => true));
+  final client = IOClient(
+    HttpClient()..badCertificateCallback = ((cert, host, port) => true),
+  );
 
   // RSS feed
   var response = await client.get(
-      Uri.parse('https://developer.apple.com/news/releases/rss/releases.rss'));
-  var channel = RssFeed.parse(response.body);
-  print(channel);
+    Uri.parse(
+      'https://developer.apple.com/news/releases/rss/releases.rss',
+    ),
+  );
+  final rssFeed = RssFeed.parse(response.body);
+  log(rssFeed.toString());
 
   // Atom feed
-  response =
-      await client.get(Uri.parse('https://www.theverge.com/rss/index.xml'));
-  var feed = AtomFeed.parse(response.body);
-  print(feed);
+  response = await client.get(
+    Uri.parse(
+      'https://www.theverge.com/rss/index.xml',
+    ),
+  );
+  final atomFeed = AtomFeed.parse(response.body);
+  log(atomFeed.toString());
 
   client.close();
 }

lib/domain/atom_category.dart

@@ -1,16 +1,24 @@
 import 'package:xml/xml.dart';
 
+/// Used for conveying information about a category associated with an entry or
+/// feed
+/// See https://tools.ietf.org/html/rfc4287#section-4.2.2
 class AtomCategory {
-  final String? term;
-  final String? scheme;
-  final String? label;
-
+  /// Default constructor for the AtomCategory class
   AtomCategory(this.term, this.scheme, this.label);
 
+  /// Parse constructor for the AtomCategory class, used when 'parsing' a feed
   factory AtomCategory.parse(XmlElement element) {
-    var term = element.getAttribute('term');
-    var scheme = element.getAttribute('scheme');
-    var label = element.getAttribute('label');
+    final term = element.getAttribute('term');
+    final scheme = element.getAttribute('scheme');
+    final label = element.getAttribute('label');
     return AtomCategory(term, scheme, label);
   }
+
+  /// The category term
+  final String? term;
+  /// The category scheme
+  final String? scheme;
+  /// The category label
+  final String? label;
 }

lib/domain/atom_feed.dart

@@ -7,22 +7,10 @@ import 'package:webfeed_revised/util/datetime.dart';
 import 'package:webfeed_revised/util/iterable.dart';
 import 'package:xml/xml.dart';
 
+/// Represents an Atom feed
+/// See https://tools.ietf.org/html/rfc4287
 class AtomFeed {
-  final String? id;
-  final String? title;
-  final DateTime? updated;
-  final List<AtomItem>? items;
-
-  final List<AtomLink>? links;
-  final List<AtomPerson>? authors;
-  final List<AtomPerson>? contributors;
-  final List<AtomCategory>? categories;
-  final AtomGenerator? generator;
-  final String? icon;
-  final String? logo;
-  final String? rights;
-  final String? subtitle;
-
+  /// Default constructor for the AtomFeed class
   AtomFeed({
     this.id,
     this.title,
@@ -39,9 +27,10 @@ class AtomFeed {
     this.subtitle,
   });
 
+  /// Parse constructor for the AtomFeed class, used when 'parsing' a feed
   factory AtomFeed.parse(String xmlString) {
-    var document = XmlDocument.parse(xmlString);
-    var feedElement = document.findElements('feed').firstOrNull;
+    final document = XmlDocument.parse(xmlString);
+    final feedElement = document.findElements('feed').firstOrNull;
     if (feedElement == null) {
       throw ArgumentError('feed not found');
     }
@@ -53,32 +42,59 @@ class AtomFeed {
           parseDateTime(feedElement.findElements('updated').firstOrNull?.text),
       items: feedElement
           .findElements('entry')
-          .map((e) => AtomItem.parse(e))
+          .map(AtomItem.parse)
           .toList(),
       links: feedElement
           .findElements('link')
-          .map((e) => AtomLink.parse(e))
+          .map(AtomLink.parse)
           .toList(),
       authors: feedElement
           .findElements('author')
-          .map((e) => AtomPerson.parse(e))
+          .map(AtomPerson.parse)
           .toList(),
       contributors: feedElement
           .findElements('contributor')
-          .map((e) => AtomPerson.parse(e))
+          .map(AtomPerson.parse)
           .toList(),
       categories: feedElement
           .findElements('category')
-          .map((e) => AtomCategory.parse(e))
+          .map(AtomCategory.parse)
           .toList(),
       generator: feedElement
           .findElements('generator')
-          .map((e) => AtomGenerator.parse(e))
+          .map(AtomGenerator.parse)
           .firstOrNull,
       icon: feedElement.findElements('icon').firstOrNull?.text,
       logo: feedElement.findElements('logo').firstOrNull?.text,
       rights: feedElement.findElements('rights').firstOrNull?.text,
       subtitle: feedElement.findElements('subtitle').firstOrNull?.text,
     );
   }
+
+  /// The feed id
+  final String? id;
+  /// The feed title
+  final String? title;
+  /// The feed updated date
+  final DateTime? updated;
+  /// The feed items
+  final List<AtomItem>? items;
+  /// The feed links
+  final List<AtomLink>? links;
+  /// The feed authors
+  final List<AtomPerson>? authors;
+  /// The feed contributors
+  final List<AtomPerson>? contributors;
+  /// The feed categories
+  final List<AtomCategory>? categories;
+  /// The feed generator
+  final AtomGenerator? generator;
+  /// The feed icon
+  final String? icon;
+  /// The feed logo
+  final String? logo;
+  /// The feed rights
+  final String? rights;
+  /// The feed subtitle
+  final String? subtitle;
 }

lib/domain/atom_generator.dart

@@ -1,16 +1,24 @@
 import 'package:xml/xml.dart';
 
+/// Used to identify the agent used to generate a feed
+/// See https://tools.ietf.org/html/rfc4287#section-4.2.4
 class AtomGenerator {
-  final String? uri;
-  final String? version;
-  final String? value;
-
+  /// Default constructor for the AtomGenerator class
   AtomGenerator(this.uri, this.version, this.value);
 
+  /// Parse constructor for the AtomGenerator class, used when 'parsing' a feed
   factory AtomGenerator.parse(XmlElement element) {
-    var uri = element.getAttribute('uri');
-    var version = element.getAttribute('version');
-    var value = element.text;
+    final uri = element.getAttribute('uri');
+    final version = element.getAttribute('version');
+    final value = element.text;
     return AtomGenerator(uri, version, value);
   }
+
+  /// The URI of the software used to generate the feed, must be an IRI
+  /// reference
+  final String? uri;
+  /// The version of the generating agent
+  final String? version;
+  /// The name of the generating agent
+  final String? value;
 }

lib/domain/atom_item.dart

@@ -7,22 +7,11 @@ import 'package:webfeed_revised/util/datetime.dart';
 import 'package:webfeed_revised/util/iterable.dart';
 import 'package:xml/xml.dart';
 
+/// Represents an Atom item
+/// See https://tools.ietf.org/html/rfc4287
 class AtomItem {
-  final String? id;
-  final String? title;
-  final DateTime? updated;
-
-  final List<AtomPerson>? authors;
-  final List<AtomLink>? links;
-  final List<AtomCategory>? categories;
-  final List<AtomPerson>? contributors;
-  final AtomSource? source;
-  final String? published;
-  final String? content;
-  final String? summary;
-  final String? rights;
-  final Media? media;
 
+  /// Default constructor for the AtomItem class
   AtomItem({
     this.id,
     this.title,
@@ -39,34 +28,60 @@ class AtomItem {
     this.media,
   });
 
-  factory AtomItem.parse(XmlElement element) {
-    return AtomItem(
+  /// Parse constructor for the AtomItem class, used when 'parsing' a feed
+  factory AtomItem.parse(XmlElement element) => AtomItem(
       id: element.findElements('id').firstOrNull?.text,
       title: element.findElements('title').firstOrNull?.text,
       updated: parseDateTime(element.findElements('updated').firstOrNull?.text),
       authors: element
           .findElements('author')
-          .map((e) => AtomPerson.parse(e))
+          .map(AtomPerson.parse)
           .toList(),
       links:
-          element.findElements('link').map((e) => AtomLink.parse(e)).toList(),
+          element.findElements('link').map(AtomLink.parse).toList(),
       categories: element
           .findElements('category')
-          .map((e) => AtomCategory.parse(e))
+          .map(AtomCategory.parse)
           .toList(),
       contributors: element
           .findElements('contributor')
-          .map((e) => AtomPerson.parse(e))
+          .map(AtomPerson.parse)
           .toList(),
       source: element
           .findElements('source')
-          .map((e) => AtomSource.parse(e))
+          .map(AtomSource.parse)
           .firstOrNull,
       published: element.findElements('published').firstOrNull?.text,
       content: element.findElements('content').firstOrNull?.text,
       summary: element.findElements('summary').firstOrNull?.text,
       rights: element.findElements('rights').firstOrNull?.text,
       media: Media.parse(element),
     );
-  }
+
+  /// The item id
+  final String? id;
+  /// The item title
+  final String? title;
+  /// The item updated date
+  final DateTime? updated;
+  /// The item authors
+  final List<AtomPerson>? authors;
+  /// The item links
+  final List<AtomLink>? links;
+  /// The item categories
+  final List<AtomCategory>? categories;
+  /// The item contributors
+  final List<AtomPerson>? contributors;
+  /// The item source
+  final AtomSource? source;
+  /// The item published date
+  final String? published;
+  /// The item content
+  final String? content;
+  /// The item summary
+  final String? summary;
+  /// The item rights
+  final String? rights;
+  /// The item media
+  final Media? media;
 }

lib/domain/atom_link.dart

@@ -1,13 +1,9 @@
 import 'package:xml/xml.dart';
 
+/// Defines a reference from an entry or feed to a Web resource
+/// See https://tools.ietf.org/html/rfc4287#section-4.2.7
 class AtomLink {
-  final String? href;
-  final String? rel;
-  final String? type;
-  final String? hreflang;
-  final String? title;
-  final int length;
-
+  /// Default constructor for the AtomLink class
   AtomLink(
     this.href,
     this.rel,
@@ -17,16 +13,30 @@ class AtomLink {
     this.length,
   );
 
+  /// Parse constructor for the AtomLink class, used when 'parsing' a feed
   factory AtomLink.parse(XmlElement element) {
-    var href = element.getAttribute('href');
-    var rel = element.getAttribute('rel');
-    var type = element.getAttribute('type');
-    var title = element.getAttribute('title');
-    var hreflang = element.getAttribute('hreflang');
+    final href = element.getAttribute('href');
+    final rel = element.getAttribute('rel');
+    final type = element.getAttribute('type');
+    final title = element.getAttribute('title');
+    final hreflang = element.getAttribute('hreflang');
     var length = 0;
     if (element.getAttribute('length') != null) {
       length = int.parse(element.getAttribute('length')!);
     }
     return AtomLink(href, rel, type, hreflang, title, length);
   }
+
+  /// The URI of the referenced resource
+  final String? href;
+  /// The link relationship type
+  final String? rel;
+  /// The media type of the referenced resource
+  final String? type;
+  /// The language of the referenced resource
+  final String? hreflang;
+  /// The human-readable information about the link
+  final String? title;
+  /// The length of the resource, in bytes
+  final int length;
 }

lib/domain/atom_person.dart

@@ -1,18 +1,23 @@
 import 'package:webfeed_revised/util/iterable.dart';
 import 'package:xml/xml.dart';
 
+/// The person element is used to specify the author of an entry or feed.
+/// See https://tools.ietf.org/html/rfc4287#section-3.2
 class AtomPerson {
-  final String? name;
-  final String? uri;
-  final String? email;
-
+  /// Default constructor for the AtomPerson class
   AtomPerson({this.name, this.uri, this.email});
 
-  factory AtomPerson.parse(XmlElement element) {
-    return AtomPerson(
+  /// Parse constructor for the AtomPerson class, used when 'parsing' a feed
+  factory AtomPerson.parse(XmlElement element) => AtomPerson(
       name: element.findElements('name').firstOrNull?.text,
       uri: element.findElements('uri').firstOrNull?.text,
       email: element.findElements('email').firstOrNull?.text,
     );
-  }
+
+  /// The name of the person
+  final String? name;
+  /// The URI of the person, must be an IRI reference
+  final String? uri;
+  /// The email of the person
+  final String? email;
 }