docs: Add public_member_api_docs lint rule and document missing APIs (#…

…223)

analysis_options.yaml

@@ -17,6 +17,7 @@ linter:
   rules: # https://dart-lang.github.io/linter/lints/{rule}.html
     - always_declare_return_types
     - annotate_overrides
+    - annotate_redeclares
     - avoid_bool_literals_in_conditional_expressions
     #    - avoid_catches_without_on_clauses # blocked on https://github.com/dart-lang/linter/issues/3023
     #    - avoid_catching_errors # blocked on https://github.com/dart-lang/linter/issues/3023
@@ -141,6 +142,7 @@ linter:
     - prefer_typing_uninitialized_variables
     - prefer_void_to_null
     - provide_deprecation_message
+    - public_member_api_docs
     - recursive_getters
     - require_trailing_commas
     - secure_pubspec_urls

examples/browser_summarizer/lib/app.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
 

examples/browser_summarizer/lib/chrome/chrome_api.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 @JS('chrome')
 library chrome;
 

examples/browser_summarizer/lib/popup/bloc/pop_up_screen_cubit.dart

@@ -1,4 +1,4 @@
-// ignore_for_file: avoid_web_libraries_in_flutter
+// ignore_for_file: avoid_web_libraries_in_flutter, public_member_api_docs
 import 'dart:js_util';
 
 import 'package:equatable/equatable.dart';

examples/browser_summarizer/lib/popup/bloc/pop_up_screen_state.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 part of 'pop_up_screen_cubit.dart';
 
 @immutable

examples/browser_summarizer/lib/popup/pop_up_screen.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
 import 'package:flutter_markdown/flutter_markdown.dart';

examples/browser_summarizer/lib/settings/settings_repository.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'package:shared_preferences/shared_preferences.dart';
 
 class SettingsRepository {

examples/hello_world_flutter/lib/app.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'package:flutter/material.dart';
 
 import 'home/home_screen.dart';

examples/hello_world_flutter/lib/home/bloc/home_screen_cubit.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'package:equatable/equatable.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';

examples/hello_world_flutter/lib/home/bloc/home_screen_state.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 part of 'home_screen_cubit.dart';
 
 @immutable

examples/hello_world_flutter/lib/home/home_screen.dart

@@ -1,3 +1,4 @@
+// ignore_for_file: public_member_api_docs
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
 

packages/chromadb/lib/src/collection.dart

@@ -465,9 +465,18 @@ class Collection {
 
 /// The items to include in the response.
 enum Include {
+  /// Include documents.
   documents,
+
+  /// Include embeddings.
   embeddings,
+
+  /// Include metadatas.
   metadatas,
+
+  /// Include distances.
   distances,
+
+  /// Include data.
   data,
 }

packages/chromadb/lib/src/embeddings/embedding_function.dart

@@ -25,20 +25,28 @@ sealed class Embeddable {
   }
 }
 
+/// {@template embeddable_document}
 /// Text document.
+/// {@endtemplate}
 class EmbeddableDocument extends Embeddable {
+  /// {@macro embeddable_document}
   const EmbeddableDocument({
     required this.document,
   });
 
+  /// The text document to embed.
   final String document;
 }
 
+/// {@template embeddable_image}
 /// Image.
+/// {@endtemplate}
 class EmbeddableImage extends Embeddable {
+  /// {@macro embeddable_image}
   const EmbeddableImage({
     required this.image,
   });
 
+  /// The image to embed.
   final String image;
 }

packages/chromadb/lib/src/loaders/data_loader.dart

@@ -1,4 +1,6 @@
+/// Data loader interface.
 abstract interface class DataLoader<T> {
+  /// Loads data from the given [uris].
   Future<T> call(final List<String> uris);
 }
 

packages/langchain/lib/src/agents/executors.dart

@@ -25,6 +25,7 @@ import 'tools/invalid.dart';
 /// instead.
 /// {@endtemplate}
 class AgentExecutor extends BaseChain {
+  /// {@macro agent_executor}
   AgentExecutor({
     required this.agent,
     super.memory,

packages/langchain/lib/src/agents/models/models.dart

@@ -20,9 +20,16 @@ class AgentAction extends BaseAgentAction {
     this.messageLog = const [],
   });
 
+  /// The name of the tool to use.
   final String tool;
+
+  /// The input to the tool.
   final Map<String, dynamic> toolInput;
+
+  /// The log of the action.
   final String log;
+
+  /// The log of the messages.
   final List<ChatMessage> messageLog;
 }
 
@@ -36,20 +43,27 @@ class AgentFinish extends BaseAgentAction {
     this.log = '',
   });
 
+  /// The return values of the agent.
   final Map<String, dynamic> returnValues;
+
+  /// The log of the action.
   final String log;
 }
 
 /// {@template agent_step}
 /// A action taken by the agent along with the observation of the action.
 /// {@endtemplate}
 class AgentStep {
+  /// {@macro agent_step}
   const AgentStep({
     required this.action,
     required this.observation,
   });
 
+  /// The action taken by the agent.
   final AgentAction action;
+
+  /// The observation of the action.
   final String observation;
 }
 

packages/langchain/lib/src/agents/tools/base.dart

@@ -184,6 +184,7 @@ abstract base class Tool extends BaseTool {
           },
         );
 
+  /// The name of the input variable.
   static const inputVar = 'input';
 
   /// Creates a [Tool] from a function.

packages/langchain/lib/src/agents/tools/exception.dart

@@ -16,6 +16,7 @@ final class ExceptionTool extends Tool {
           description: 'Called when the agent throws an OutputParserException',
         );
 
+  /// The name of the tool.
   static const toolName = '_exception';
 
   @override

packages/langchain/lib/src/chains/conversation.dart

@@ -54,6 +54,7 @@ class ConversationChain extends LLMChain {
     super.outputKey = 'response',
   }) : super(memory: memory ?? ConversationBufferMemory(memoryKey: _memoryKey));
 
+  /// The key of the input value.
   final String inputKey;
 
   @override

packages/langchain/lib/src/core/runnable/base.dart

@@ -43,6 +43,7 @@ import 'sequence.dart';
 /// {@endtemplate}
 abstract class Runnable<RunInput extends Object?,
     CallOptions extends BaseLangChainOptions, RunOutput extends Object?> {
+  /// {@macro runnable}
   const Runnable();
 
   /// Creates a [RunnableSequence] from a list of [Runnable] objects.

packages/langchain/lib/src/core/runnable/input_getter.dart

@@ -38,6 +38,7 @@ import 'base.dart';
 /// print(res);
 /// // Aceptamos los siguientes métodos de pago: iDEAL y PayPal.
 /// ```
+/// {@endtemplate}
 class RunnableItemFromMap<RunOutput extends Object>
     extends Runnable<Map<String, dynamic>, BaseLangChainOptions, RunOutput> {
   /// {@macro runnable_item_from_map}
@@ -96,8 +97,10 @@ class RunnableItemFromMap<RunOutput extends Object>
 /// print(res);
 /// // Why don't bears wear shoes? Because they have bear feet!
 /// ```
+/// {@endtemplate}
 class RunnableMapFromItem<RunInput extends Object>
     extends Runnable<RunInput, BaseLangChainOptions, Map<String, dynamic>> {
+  /// {@macro runnable_map_from_item}
   const RunnableMapFromItem(this.key);
 
   /// The key where to place the input in the output map.

packages/langchain/lib/src/documents/embeddings/cache.dart

@@ -114,14 +114,21 @@ class CacheBackedEmbeddings implements Embeddings {
   }
 }
 
+/// {@template embeddings_byte_store_encoder}
+/// Encoder that transforms values to and from bytes.
+/// {@endtemplate}
 class EmbeddingsByteStoreEncoder
     implements StoreEncoder<String, List<double>, String, Uint8List> {
+  /// {@macro embeddings_byte_store_encoder}
   const EmbeddingsByteStoreEncoder({
     this.namespace = '',
     this.uuid = const Uuid(),
   });
 
+  /// The namespace to use for the cache keys.
   final String namespace;
+
+  /// The uuid generator to use for generating the cache keys.
   final Uuid uuid;
 
   @override

packages/langchain/lib/src/documents/models/models.dart

@@ -24,6 +24,7 @@ class Document {
   /// The metadata of the document.
   final Map<String, dynamic> metadata;
 
+  /// Creates a document from a map.
   factory Document.fromMap(final Map<String, dynamic> map) {
     return Document(
       id: map['id'] as String?,
@@ -32,6 +33,7 @@ class Document {
     );
   }
 
+  /// Converts the document to a map.
   Map<String, dynamic> toMap() {
     return {
       'id': id,
@@ -40,6 +42,7 @@ class Document {
     };
   }
 
+  /// Creates a copy of the document.
   Document copyWith({
     final String? id,
     final String? pageContent,

packages/langchain/lib/src/documents/transformers/text_splitters/character.dart

@@ -18,6 +18,7 @@ class CharacterTextSplitter extends TextSplitter {
     super.addStartIndex,
   });
 
+  /// The separator that is used to split the text.
   final String separator;
 
   @override

packages/langchain/lib/src/documents/transformers/text_splitters/code.dart

@@ -7,6 +7,7 @@ import 'recursive_character.dart';
 /// flow statements.
 /// {@endtemplate}
 class CodeTextSplitter extends RecursiveCharacterTextSplitter {
+  /// {@macro code_text_splitter}
   CodeTextSplitter({
     required final CodeLanguage language,
     super.chunkSize,

packages/langchain/lib/src/documents/transformers/text_splitters/recursive_character.dart

@@ -16,6 +16,7 @@ class RecursiveCharacterTextSplitter extends TextSplitter {
     super.addStartIndex = false,
   });
 
+  /// List of separators to use for splitting.
   final List<String> separators;
 
   @override

packages/langchain/lib/src/documents/transformers/text_splitters/text_splitter.dart

@@ -8,6 +8,7 @@ import '../base.dart';
 /// Interface for splitting text into chunks.
 /// {@endtemplate}
 abstract class TextSplitter extends BaseDocumentTransformer {
+  /// {@macro text_splitter}
   const TextSplitter({
     this.chunkSize = 4000,
     this.chunkOverlap = 200,

packages/langchain/lib/src/memory/simple.dart

@@ -6,10 +6,12 @@ import 'models/models.dart';
 /// shouldn't ever change between prompts.
 /// {@endtemplate}
 final class SimpleMemory implements BaseMemory {
+  /// {@macro simple_memory}
   const SimpleMemory({
     this.memories = const {},
   });
 
+  /// The memories to store.
   final Map<String, dynamic> memories;
 
   @override

packages/langchain/lib/src/model_io/chat_models/models/models.dart

@@ -469,7 +469,19 @@ CustomChatMessage{
 }
 
 /// Role of a chat message
-enum ChatMessageRole { system, human, ai, custom }
+enum ChatMessageRole {
+  /// A system message.
+  system,
+
+  /// A human (user) message.
+  human,
+
+  /// An AI message.
+  ai,
+
+  /// A message with a custom role.
+  custom,
+}
 
 /// {@template chat_message_content}
 /// The content of a message.
@@ -594,7 +606,16 @@ ChatMessageContentMultiModal{
 }
 
 /// Specifies the detail level of the image.
-enum ChatMessageContentImageDetail { auto, low, high }
+enum ChatMessageContentImageDetail {
+  /// Automatically select the detail level.
+  auto,
+
+  /// Low detail level (faster response time and lower token usage).
+  low,
+
+  /// Medium detail level (slower response time and higher token usage).
+  high,
+}
 
 /// {@template chat_function}
 /// The description of a function that can be called by the chat model.
@@ -681,6 +702,7 @@ final class ChatFunctionCallAuto extends ChatFunctionCall {
 /// The model is forced to to call the specified function.
 /// {@endtemplate}
 final class ChatFunctionCallForced extends ChatFunctionCall {
+  /// {@macro chat_function_call_forced}
   const ChatFunctionCallForced({
     required this.functionName,
   });

packages/langchain/lib/src/model_io/output_parsers/functions.dart

@@ -48,6 +48,7 @@ abstract class BaseOutputFunctionsParser<
     );
   }
 
+  /// Parses the output of a function call.
   @protected
   Future<O> parseFunctionCall(final AIChatMessageFunctionCall? functionCall);
 }

packages/langchain/lib/src/model_io/prompts/base_prompt.dart

@@ -78,6 +78,7 @@ abstract base class BasePromptTemplate
   /// - [values] - Any arguments to be passed to the prompt template.
   PromptValue formatPrompt(final InputValues values);
 
+  /// Merge the partial variables with the user variables.
   @protected
   Map<String, Object> mergePartialAndUserVariables(
     final Map<String, dynamic> userVariables,