@@ -20,6 +20,7 @@ use helix_lsp::util::LspFormatting;
2020
2121use crate::{DocumentId, Theme, ViewId};
2222
23+/// 8kB of buffer space for encoding and decoding `Rope`s.
2324const BUF_SIZE: usize = 8192;
2425
2526#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
@@ -437,6 +438,7 @@ impl Document {
437438 theme: Option<&Theme>,
438439 config_loader: Option<&syntax::Loader>,
439440 ) -> Result<Self, Error> {
441+ // Open the file if it exists, otherwise assume it is a new file (and thus empty).
440442 let (rope, encoding) = if path.exists() {
441443 let mut file =
442444 std::fs::File::open(path).context(format!("unable to open {:?}", path))?;
@@ -564,6 +566,7 @@ impl Document {
564566 }
565567 }
566568
569+ /// Detect the programming language based on the file type.
567570 pub fn detect_language(&mut self, theme: Option<&Theme>, config_loader: &syntax::Loader) {
568571 if let Some(path) = &self.path {
569572 let language_config = config_loader.language_config_for_file_name(path);
@@ -571,6 +574,10 @@ impl Document {
571574 }
572575 }
573576
577+ /// Detect the indentation used in the file, or otherwise defaults to the language indentation
578+ /// configured in `languages.toml`, with a fallback back to 2 space indentation if it isn't
579+ /// specified. Line ending is likewise auto-detected, and will fallback to the default OS
580+ /// line ending.
574581 pub fn detect_indent_and_line_ending(&mut self) {
575582 self.indent_style = auto_detect_indent_style(&self.text).unwrap_or_else(|| {
576583 IndentStyle::from_str(
@@ -596,6 +603,9 @@ impl Document {
596603 let mut file = std::fs::File::open(path.unwrap())?;
597604 let (rope, ..) = from_reader(&mut file, Some(encoding))?;
598605
606+ // Calculate the difference between the buffer and source text, and apply it.
607+ // This is not considered a modification of the contents of the file regardless
608+ // of the encoding.
599609 let transaction = helix_core::diff::compare_ropes(self.text(), &rope);
600610 self.apply(&transaction, view_id);
601611 self.append_changes_to_history(view_id);
@@ -630,6 +640,8 @@ impl Document {
630640 Ok(())
631641 }
632642
643+ /// Set the programming language for the file and load associated data (e.g. highlighting)
644+ /// if it exists.
633645 pub fn set_language(
634646 &mut self,
635647 theme: Option<&Theme>,
@@ -650,6 +662,8 @@ impl Document {
650662 };
651663 }
652664
665+ /// Set the programming language for the file if you know the name (scope) but don't have the
666+ /// [`syntax::LanguageConfiguration`] for it.
653667 pub fn set_language2(
654668 &mut self,
655669 scope: &str,
@@ -661,16 +675,19 @@ impl Document {
661675 self.set_language(theme, language_config);
662676 }
663677
678+ /// Set the LSP.
664679 pub fn set_language_server(&mut self, language_server: Option<Arc<helix_lsp::Client>>) {
665680 self.language_server = language_server;
666681 }
667682
683+ /// Select text within the [`Document`].
668684 pub fn set_selection(&mut self, view_id: ViewId, selection: Selection) {
669685 // TODO: use a transaction?
670686 self.selections
671687 .insert(view_id, selection.ensure_invariants(self.text().slice(..)));
672688 }
673689
690+ /// Apply a [`Transaction`] to the [`Document`] to change its text.
674691 fn apply_impl(&mut self, transaction: &Transaction, view_id: ViewId) -> bool {
675692 let old_doc = self.text().clone();
676693
@@ -733,6 +750,7 @@ impl Document {
733750 success
734751 }
735752
753+ /// Apply a [`Transaction`] to the [`Document`] to change its text.
736754 pub fn apply(&mut self, transaction: &Transaction, view_id: ViewId) -> bool {
737755 // store the state just before any changes are made. This allows us to undo to the
738756 // state just before a transaction was applied.
@@ -754,6 +772,7 @@ impl Document {
754772 success
755773 }
756774
775+ /// Undo the last modification to the [`Document`].
757776 pub fn undo(&mut self, view_id: ViewId) {
758777 let mut history = self.history.take();
759778 let success = if let Some(transaction) = history.undo() {
@@ -769,6 +788,7 @@ impl Document {
769788 }
770789 }
771790
791+ /// Redo the last modification to the [`Document`].
772792 pub fn redo(&mut self, view_id: ViewId) {
773793 let mut history = self.history.take();
774794 let success = if let Some(transaction) = history.redo() {
@@ -784,6 +804,7 @@ impl Document {
784804 }
785805 }
786806
807+ /// Undo modifications to the [`Document`] according to `uk`.
787808 pub fn earlier(&mut self, view_id: ViewId, uk: helix_core::history::UndoKind) {
788809 let txns = self.history.get_mut().earlier(uk);
789810 for txn in txns {
@@ -791,6 +812,7 @@ impl Document {
791812 }
792813 }
793814
815+ /// Redo modifications to the [`Document`] according to `uk`.
794816 pub fn later(&mut self, view_id: ViewId, uk: helix_core::history::UndoKind) {
795817 let txns = self.history.get_mut().later(uk);
796818 for txn in txns {
@@ -823,6 +845,7 @@ impl Document {
823845 self.id
824846 }
825847
848+ /// If there are unsaved modifications.
826849 pub fn is_modified(&self) -> bool {
827850 let history = self.history.take();
828851 let current_revision = history.current_revision();
@@ -830,6 +853,7 @@ impl Document {
830853 current_revision != self.last_saved_revision || !self.changes.is_empty()
831854 }
832855
856+ /// Save modifications to history, and so [`Self::is_modified`] will return false.
833857 pub fn reset_modified(&mut self) {
834858 let history = self.history.take();
835859 let current_revision = history.current_revision();
@@ -837,6 +861,7 @@ impl Document {
837861 self.last_saved_revision = current_revision;
838862 }
839863
864+ /// Current editing mode for the [`Document`].
840865 pub fn mode(&self) -> Mode {
841866 self.mode
842867 }
@@ -848,6 +873,7 @@ impl Document {
848873 .map(|language| language.scope.as_str())
849874 }
850875
876+ /// Corresponding [`LanguageConfiguration`].
851877 pub fn language_config(&self) -> Option<&LanguageConfiguration> {
852878 self.language.as_deref()
853879 }
@@ -890,6 +916,7 @@ impl Document {
890916 self.path.as_ref()
891917 }
892918
919+ /// File path as a URL.
893920 pub fn url(&self) -> Option<Url> {
894921 self.path().map(|path| Url::from_file_path(path).unwrap())
895922 }