Patent Description:
Textual files are used in a variety of fields to describe one or more structures of the field, where the textual file is formatted in an identified scheme of the field. One example is the field of software code development, where a source file of a software program is formatted according to a schema of a programming language or a data object, for example a JavaScript Object Notation (JSON) file. Another example is a repository of procedures, for example test protocols or customer service procedures, where a source file describes one or more procedures or protocols of a field. Yet another example is a repository of documents stored in an identified format, for example a Google Docs repository or a repository comprising documents in Microsoft Word format.

As used herein, the term documentation refers to text that accompanies a file, or part of a file, in order to describe the file or the part of the file for a human. Documentation may include one or more images in addition to, or instead of, the text. Some documentation explains a structure described by the file. Some documentation explains how to use the file or a system produced using the file. Some documentation explains how a procedure described by the file works. Some documentation explains how a system produced using the file works.

There exist environments where one or more of a plurality of files are modified over time, for example source code files in a development environment. In such environments, documentation text describing an early version of a file may no longer explain, or describe, correctly a later version of the file.

To preserve the relevance of documentation text to a file, or part of a file, described thereby, there is a need to update the documentation text in a manner synchronous with modifications to the file.

Prior attempts have been made to address documentation maintenance. <CIT> discloses a system for managing changes to files using mapping records to track changes and their significance. However, this system only tracks changes without providing mechanisms for documentation updates. <CIT> discloses a system for generating hypertext documentation from source code, but does not address maintaining synchronization between documentation and code as changes occur.

Some embodiments of the present disclosure describe a system and a method for automatically updating one or more source documentation objects documenting one or more segments of one or more source files.

According to a first aspect of the invention, a method comprises executing a code in a development environment comprising a file version control system (VCS) for: documenting each of a plurality of marked segments in one of a plurality of source documentation objects associated therewith, each marked segment comprising at least part of one of a plurality of versions of one of a plurality of source files managed by the VCS, where each source documentation object comprises a copy of the marked segment documented thereby organized as a documentation patch instructing removal of the marked segment from the version of the source file; identifying in the VCS a new version of a source file of the plurality of source files, where the new version was added to the VCS after a version of the source file having a marked segment documented by a source documentation object of the plurality of source documentation objects; performing an identification of when an updated segment in the new version of the source file, equivalent to the marked segment, is different from the marked segment, by: applying the copy of the marked segment as a documentation patch to the new version of the source file; and identifying the updated segment is different from the marked segment when application of the documentation patch fails; and in response to the identification: classifying the updated segment as one of a set of change classifications according to one or more differences identified between the updated segment and the copy of the marked segment; and subject to the change classification being a member of a set of updatable changes, generating an updated source documentation object by modifying the copy of the marked segment according to the change classification and the one or more differences. Generating the updated source documentation object according to the change classification in addition to the one or more differences increases accuracy of the updated source documentation object compared to generating the updated source documentation object according to the one or more differences alone.

According to a second aspect of the invention, an apparatus comprises at least one hardware processor configured for executing a code in a development environment comprising a file version control system (VCS) for: documenting each of a plurality of marked segments in one of a plurality of source documentation objects associated therewith, each marked segment comprising at least part of one of a plurality of versions of one of a plurality of source files managed by the VCS, where each source documentation object comprises a copy of the marked segment documented thereby organized as a documentation patch instructing removal of the marked segment from the version of the source file; identifying in the VCS a new version of a source file of the plurality of source files, where the new version was added to the VCS after a version of the source file having a marked segment documented by a source documentation object of the plurality of source documentation objects; performing an identification of when an updated segment in the new version of the source file, equivalent to the marked segment, is different from the marked segment, by: applying the copy of the marked segment as a documentation patch to the new version of the source file; and identifying the updated segment is different from the marked segment when application of the documentation patch fails; and in response to the identification: classifying the updated segment as one of a set of change classifications according to one or more differences identified between the updated segment and the copy of the marked segment; and subject to the change classification being a member of a set of updatable changes, generating an updated source documentation object by modifying the copy of the marked segment according to the change classification and the one or more differences.

According to a third aspect of the invention, a software program product for a development environment comprises: a non-transitory computer readable storage medium; first program instructions for documenting each of a plurality of marked segments in one of a plurality of source documentation objects associated therewith, each marked segment comprising at least part of one of a plurality of versions of one of a plurality of source files managed by a VCS, where each source documentation object comprises a copy of the marked segment documented thereby organized as a documentation patch instructing removal of the marked segment from the version of the source file; second program instructions for identifying in the VCS a new version of a source file of the plurality of source files, where the new version was added to the VCS after a version of the source file having a marked segment documented by a source documentation object of the plurality of source documentation objects; third program instructions for performing an identification of when an updated segment in the new version of the source file, equivalent to the marked segment, is different from the marked segment, by: applying the copy of the marked segment as a documentation patch to the new version of the source file; and identifying the updated segment is different from the marked segment when application of the documentation patch fails; and fourth program instructions for in response to the identification: classifying the updated segment as one of a set of change classifications according to one or more differences identified between the updated segment and the copy of the marked segment; and subject to the change classification being a member of a set of updatable changes, generating an updated source documentation object by modifying the copy of the marked segment according to the change classification and the one or more differences; and the first, second, third and fourth program instructions are executed by at least one computerized processor from the non-transitory computer readable storage medium.

With reference to the first and second aspects, in a first possible implementation of the first and second aspects of the present invention the plurality of source documentation objects is organized in at least one documentation file each having a plurality of documentation versions, the plurality of documentation versions of the at least one documentation file are managed by another VCS, and each documentation version of the at least one documentation file in the other VCS is associated with a version of at least one of the plurality of source files in the VCS. Organizing the plurality of documentation objects in at least one documentation file allows using existing VCS solutions to manage the plurality of versions of the plurality of documentation objects for the plurality of versions of the plurality of source files, thus reducing cost of management thereof.

With reference to the first and second aspects, in a second possible implementation of the first and second aspects of the present invention the source file is organized in a plurality of lines and the copy of the marked segment comprises one or more documentation line changes between the version of the source file and a virtual file created by removing the marked segment from the version of the source file. Including in the copy of the marked segment one or more documentation line changes indicative of removing the marked segment from the version of the source file facilitates using existing patch-application development resources, reducing cost of implementation and complexity of a system implemented according to some embodiments described herein. Optionally, the method further comprises applying the one or more documentation line changes to the version of the source file to produce the virtual file. Optionally, the updated segment in the new version of the source file is identified when performing an application of the one or more documentation line changes to the version of the source file, and identifying that the updated segment is different from the marked segment is by failing to perform the application. Optionally, classifying the updated segment comprises: computing at least one source line change between the new version of the source file and the version of the source file; and computing the change classification by analyzing the one or more documentation line changes and the at least one source line change to identify the one or more differences between the updated segment and the copy of the marked segment. Optionally, computing the change classification comprises: classifying each of the one or more documentation line changes as one of a set of line-change classifications by analyzing the one or more documentation line changes and the at least one source line change to identify the one or more differences between the updated segment and the copy of the marked segment, to produce a plurality of line-change classifications; and computing the change classification by analyzing the plurality of line-change classifications. Computing the change classification by analyzing the plurality of line-change classifications increases accuracy of the change classification compared to other methods that classify the updated segment as a whole. Optionally, at least one documentation line change of the one or more documentation line changes is classified as "line change to lint-characters" and computing the change classification further comprises replacing in the copy of the marked segment the at least one documentation line change with an equivalent line of the updated segment.

With reference to the first and second aspects, in a third possible implementation of the first and second aspects of the present invention classifying the updated segment comprises identifying at least one of: a file name of the new version of the source file is different from another file name of the version of the source file, and a file path of the new version of the source file is different from another file path of the version of the source file. Optionally, generating the updated source documentation object further comprises modifying the updated source documentation object using the file name and additionally or alternatively the file path. Identifying a new file name and additionally or alternatively a new file path increase accuracy of the updated digital documentation modified therewith.

With reference to the first and second aspects, in a fourth possible implementation of the first and second aspects of the present invention the source documentation object further comprises a textual description describing the marked segment and generating the updated source documentation object further comprises: identifying at least one token present in the textual description and the one or more differences identified between the updated segment and the copy of the marked segment; identifying in the one or more differences at least one updated token equivalent to the at least one token; and generating an updated textual description by replacing in the textual description the at least one token with the at least one updated token.

With reference to the first and second aspects, in a fifth possible implementation of the first and second aspects of the present invention the set of change classifications consists of "change to lint-characters", "change to an inner block", "updatable single line change", "no change", and "non-updatable change"; and the set of updatable changes consists of "change to lint-characters", "change to an inner block", and "updatable single line change". Optionally, the method further comprises subject to the change classification being "non-updatable change", generating the updated source documentation object using the copy of the marked segment and by marking the copy of the marked segment is obsolete; and subject to the change classification being "no change", generating the updated source documentation object using the copy of the marked segment.

With reference to the first and second aspects, in a sixth possible implementation of the first and second aspects of the present invention the method further comprises: identifying in the VCS at least one other new version of the source file where each of the at least one other new version was added to the VCS after the version of the source file documented in the source documentation object and before the new version of the source file; organizing the at least one other new version of the source file and the new version of the source file in ascending order of addition to the VCS, to produce a sequence of versions of the source file; and in each of a plurality of iterations: performing an identification of when another updated segment in a consecutive version of the source file, immediately following the version of the source file in the sequence of versions of the source file, equivalent to the marked segment, is different from the marked segment; and in response to the identification: classifying the other updated segment as one of a set of change classifications according to one or more differences identified between the updated segment and the copy of the marked segment; and subject to the change classification being a member of a set of updatable changes, generating the updated source documentation object by modifying the copy of the marked segment according to the change classification and the one or more differences; using the consecutive version of the source file as the source file in a next iteration of the plurality of iterations; and using the updated source documentation object as the source documentation object in the next iteration. Generating the updated documentation object in a plurality of iterations increases a likelihood of the change classification being a member of the set of updateable changes and thus increases a likelihood of automatically updating the copy of the marked segment, increasing usability of a system implemented according to the present disclosure.

With reference to the first and second aspects, in a seventh possible implementation of the first and second aspects of the present invention each of the plurality of versions of the source file is associated with a checksum value, and the source documentation object further comprises the respective checksum value associated with the version of the source file. With reference to the first and second aspects, in an eighth possible implementation of the first and second aspects of the present invention the method further comprises associating the updated source documentation object with the new version of the source file, and documenting the new version of the source file with the updated source documentation object.

With reference to the first and second aspects, in a ninth possible implementation of the first and second aspects of the present invention the method further comprises retrieving from the VCS the version of the source file and the new version of the source file.

Unless otherwise defined, all technical and/or scientific terms used herein have the same meaning as commonly understood by one of ordinary skill in the art to which embodiments. Although methods and materials similar or equivalent to those described herein can be used in the practice or testing of embodiments, exemplary methods and/or materials are described below.

Some embodiments are herein described, by way of example only, with reference to the accompanying drawings. With specific reference now to the drawings in detail, it is stressed that the particulars shown are by way of example and for purposes of illustrative discussion of embodiments. In this regard, the description taken with the drawings makes apparent to those skilled in the art how embodiments may be practiced.

The following description focuses on, but is not limited to, updating documentation in a software development environment where a plurality of source files is a plurality of software code source files. However, embodiments are not limited to the field of software development. Some other possible embodiments include a plurality of source files that are not software code source files, for example a plurality of test protocols, a plurality of customer service procedures or a plurality of Microsoft Word documents.

Documentation of a plurality of source files of a system that is no longer relevant, for example due to being outdated, may have a negative impact on usage of the system, or of another system generated thereby. In addition, when the plurality of source files is used to create another system, outdated documentation makes it difficult to correctly maintain the other system and additionally or alternatively correctly create it. However, despite long-term costs of poor documentation, manually writing documentation to describe the plurality of source files comes at a cost to developers of the plurality of source files, and frequently offers little immediate benefit. When a plurality of source files of an environment changes frequently, manually updating the documentation in step with the changes to the source files is cumbersome and time consuming, and as a result is often neglected, rendering the documentation irrelevant.

There exist solutions for assisting in creating documentation that automatically generate syntactic documentation providing a syntactic description of one or more structures described by the plurality of source files. For example, in a software development environment, such a solution may generate a set of interface functions, listing for each its arguments and their types. When a definition of an interface function changes, new documentation may be generated. However, some such solutions do not automatically generate semantic documentation explaining the source files, for example explaining how a function operates, and do not update a manually created documentation entry when a source file changes.

There exist other solutions that generate documentation for a plurality of source files of a software program from testing processes of the software program. Such solutions cannot be applied when no testing processes exist, or for source files not covered by the testing processes.

Some other existing solutions insert into the source file a textual token to mark at least part of the source file documented by a manually created documentation entry. In addition, such solutions may digitally sign the documented part of the source file by inserting into the source file a digital signature, for example a hash value computed using the documented part of the source file. However, such solutions modify the source files themselves, making the source files less legible to a user using them. In addition, these solutions are susceptible to problems rising from a user inadvertently corrupting the digital signature or the textual token, for example when modifying the source file for development purposes.

A file version control system (VCS) is a program designed to handle a plurality of versions of one or more files. To allow automatic updating of documentation of a plurality of source files, some embodiments described herewithin propose documenting a marked segment of a version of a source file managed by a VCS using a source documentation object comprising a copy of the marked segment. Optionally, the source documentation object comprises a textual description associated with the marked segment. Optionally, the version of the source file is one of a plurality of versions of the source file, managed by the VCS. When a new version of the source file is identified in the VCS, in such embodiments an updated segment in the new version, equivalent to the marked segment, is classified as one of a set of change classifications and an updated source documentation object is optionally generated by modifying the copy of the marked segment according to the change classification and one or more differences identified between the updated segment and the copy of the marked segment. Some examples of a change classification are "no change", "change to context", "change to an inner block", and "non-updatable changes". Optionally, the updated source documentation object is generated subject to the change classification being a member of a set of updatable changes, for example "change to an inner block". Optionally, classifying the updated segment as one of the set of change classifications is according to the one or more differences between the updated segment and the copy of the marked segment. Modifying the copy of the marked segment according to the change classification increases accuracy of the updated source documentation object compared to generating the updated source documentation object using other methods that apply generic modifications, not adjusted according to the change classification, for example methods that generate syntactic documentation.

Optionally, the source documentation object is associated with the version of the source file comprising the marked segment. Optionally, the updated source documentation object is associated with the new version of the source file, comprising the updated segment equivalent to the marked segment of the version of the source file. Using a VCS to manage the source file allows using one or more VCS values to identify the version of the source file and distinguish the version of the source file from the new version of the source file, for example a respective checksum value associated with each of the source file's plurality of versions. Using the one or more VCS values to identify the version of the source file facilitates using existing development resources, reducing cost of implementation and ease of use of the method described above compared to other methods that rely on proprietary means of associating a version of documentation with a version of a source file. Associating the source documentation object with the version of the source file allows annotating the version of the source file with at least part of the source documentation object, for example in a development environment, for example by displaying at least part of the copy of the marked segment and additionally or alternatively at least part of the textual description associated with the marked segment as an annotation to the marked segment. Similarly, associating the updated source documentation object with the new version of the source file allows annotating the new version of the source file with at least part of the updated source documentation object, increasing accuracy of automatic annotation of each version of the file. Increasing accuracy of automatic annotation of each version of the file increases usability of a development system using the plurality of versions of the plurality of files, for example by increasing legibility of the plurality of versions of the plurality of source files to a human user of the development system.

Optionally, the source documentation object is one of a plurality of source documentation objects, each documenting one of a plurality of marked segments, each marked segment comprising at least part of one of a plurality of versions of one of the plurality of source files. Optionally, the source documentation object documents the entire version of the source file, i.e. the marked segment comprises the entire version of the source file. When the source documentation object documents the entire version of the source file, optionally the source documentation object comprises a link to the version of the source file instead of the marked segment.

As used herewithin, the term "patch" refers to a plurality of differences between two versions of a file organized in a format that describes how to modify one version of the file in order to produce another version of the file. Thus, the term "applying a patch", as used herewithin, refers to applying the one or more changes to the one version of the file in order to produce the other version of the file.

When a file is organized in a plurality of lines, one common format for describing a plurality of differences between a first version and a second version of the file is the context format. In the context format, any changed lines of the second file are shown alongside some unchanged lines before and after, providing a context to the plurality of differences. Such a context serves as a reference to locate in the first file a location for one or more changes to be applied in order to produce the changed lines of the second file. A patch file may be organized in a plurality of hunks, each hunk describing a location in the first file identified by one or more line numbers of the first file and comprising one or more lines of the first version, and an equivalent location in the second file identified by one or more other line numbers of the second file and comprising one or more new lines of the second version. In the context format, the one or more lines of the first version comprise one or more unchanged lines that are the same in both the first file and the second file, and additionally or alternatively one or more removed lines each preceded by a token indicating the line is a line removed from the first version and additionally or alternatively one or more updated lines each preceded by a token indicating the line is a line modified in the second version. In addition, in the context format the one or more lines of the second version comprise the one or more unchanged lines that are the same in both the first file and the second file, and additionally or alternatively one or more added lines each preceded by a token indicating the line is a new line added to the second version and additionally or alternatively one or more new updated lines each preceded by a token indicating the line is a new line modified in the second version from a line of the first version.

Another existing format for describing the plurality of differences between the first version and the second version is the unified differences format. Similar to the context format, in the unified differences format a patch file may be organized in a plurality of hunks, each hunk describing a location in the first file identified by one or more line numbers of the first file, and an equivalent location in the second file identified by one or more other line numbers of the second file. However, in the unified differences format there is no indication of a modified line, and instead a plurality of consecutive modified lines is represented by two changes presented immediately adjacent - removal of a plurality of lines from the first version and addition of a plurality of new lines to the second version.

It is common practice to organize a patch in the unified differences format. To apply such a patch to a file, for each hunk of the plurality of hunks the file must comprise one or more file lines that are equal to the one or more lines of the first file. In some cases, the one or more file lines must be at a file location in the file, the file location identified by the one or more line number in the first file. In such cases, when the file has at the file location one or more file lines that are different from the one or more lines of the first file, the patch cannot be applied as the file is different from the first file.

The present disclosure additionally proposes organizing the copy of the marked segment as a documentation patch instructing removal of the marked segment from the version of the source file. Such a documentation patch describes one or more documentation line changes between the version of the source file and a virtual file created by removing the marked segment from the version of the source file. Successfully applying such a documentation patch to another version of the source file is indicative of the marked segment being unchanged in the other version of the source file. Thus, the present disclosure proposes identifying the copy of the marked segment is different from the updated segment subject to a failure to apply the copy of the marked segment as a patch to the new version of the source file.

Applying the copy of the marked segment as a patch is by executing a patch method of the VCS. Using a patch method of the VCS reduces complexity of a system compared to using a proprietary compare method, thus increasing usability.

In addition, it may be the case that after the version of the source file was added to the VCS, more than one other version of the source file was added to the VCS, each at a time of addition to thereof. In some embodiments, the present disclosure additionally proposes organizing the more than one other version in a sequence of versions of the source file, in ascending order of the respective time of addition to the VCS thereof, and generating the updated source documentation object in a plurality of iterations. Optionally, in each of the plurality of iterations the updated source documentation object is generated using a consecutive version of the source file, immediately following the version of the source file in the sequence of the versions of the source file. Optionally, the consecutive version of the source file is used as the source file in a next iteration of the plurality of iterations, and the updated documentation object is used as the source documentation object in the next iteration. Generating the updated documentation object in a plurality of iterations increases a likelihood of the change classification being a member of the set of updateable changes and thus increases a likelihood of automatically updating the copy of the marked segment, increasing usability of a system implemented according to the present disclosure.

In addition, the present disclosure proposes in some embodiments described herewithin, to compute the change classification by analyzing a plurality of line-change classifications, each classifying the one or more documentation line changes as described by the copy of the marked segment of the documentation patch. Computing the change classification by analyzing the plurality of line-change classifications increases accuracy of the change classification compared to analyzing the updated segment as a monolithic block.

For example, a change to an inner block may be one or more changes to a marked segment organized in a plurality of lines where none of the one or more changes are in a first line of the marked segment or in a last line of the marked segment. In this example, a change classification of "change to an inner block" may be determined when identifying that a first and last lines of the copy of the marked segment are respectively equal to the first and last lines of the updated segment. When the one or more differences between the updated segment and the copy of the marked segment are in one or more lines that are not the first or last lines of the copy of the marked segment or the updated segment, there is an increased likelihood that a textual description associated with the marked segment is relevant to the updated segment, and thus the updated source documentation object may be generated using the textual description and the updated segment.

In another example, after determining the change classification is not "change to an inner block", a change classification of "updatable single line change" may be determined when identifying the one or more differences comprise one or more token differences to an amount of tokens of one line of the copy of the marked segment. When an amount of the one or more token differences is below an identified threshold, there is an increased likelihood that the textual description associated with the marked segment is relevant to the updated segment, and thus the updated source documentation object may be generated using the textual description and the updated segment.

Before explaining at least one embodiment in detail, it is to be understood that embodiments are not necessarily limited in its application to the details of construction and the arrangement of the components and/or methods set forth in the following description and/or illustrated in the drawings and/or the Examples. Implementations described herein are capable of other embodiments or of being practiced or carried out in various ways.

Embodiments may be a system, a method, and/or a computer program product. The computer program product may include a computer readable storage medium (or media) having computer readable program instructions thereon for causing a processor to carry out aspects of the embodiments.

A non-exhaustive list of more specific examples of the computer readable storage medium includes the following: a portable computer diskette, a hard disk, a random access memory (RAM), a read-only memory (ROM), an erasable programmable read-only memory (EPROM or Flash memory), a static random access memory (SRAM), a portable compact disc read-only memory (CD-ROM), a digital versatile disk (DVD), a memory stick, a floppy disk, and any suitable combination of the foregoing.

Computer readable program instructions for carrying out operations of embodiments may be assembler instructions, instruction-set-architecture (ISA) instructions, machine instructions, machine dependent instructions, microcode, firmware instructions, state-setting data, or either source code or object code written in any combination of one or more programming languages, including an object oriented programming language such as Smalltalk, C++ or the like, and conventional procedural programming languages, such as the "C" programming language or similar programming languages. In some embodiments, electronic circuitry including, for example, programmable logic circuitry, field-programmable gate arrays (FPGA), or programmable logic arrays (PLA) may execute the computer readable program instructions by utilizing state information of the computer readable program instructions to personalize the electronic circuitry, in order to perform aspects of embodiments.

Aspects of embodiments are described herein with reference to flowchart illustrations and/or block diagrams of methods, apparatus (systems), and computer program products according to embodiments.

For brevity, henceforth the term "documentation object" is used to mean "source documentation object", and the terms are used interchangeably.

Reference is now made to <FIG>, showing a schematic block diagram of exemplary documentation <NUM>, according to some embodiments. In such embodiments, a version of a source file <NUM> comprises one or more marked segments, for example marked segment <NUM> and marked segment <NUM>. Optionally, source documentation object <NUM> documents marked segment <NUM>. Optionally, documentation object <NUM> comprises a copy of marked segment 111A. When version of the source file <NUM> is organized in a plurality of lines, the copy of marked segment 111A optionally comprises one or more documentation line changes between the version of the source file and a virtual file created by removing marked segment <NUM> from version of the source file <NUM>. When marked segment <NUM> is the entire version of the source file <NUM>, the copy of marked segment 111A optionally comprises a reference to version of the source file <NUM>. Optionally, the copy of marked segment 111A is formatted in unified differences format. Optionally, copy of marked segment 111A comprises one or more unmarked documentation lines preceding, and additionally or alternatively following, marked segment <NUM> in version of the source file <NUM>.

Optionally, documentation object <NUM> is one of a plurality of documentation objects, each documenting another marked segment of a plurality of marked segments. For example, another of the plurality of documentation objects may document marked segment <NUM>. Yet another of the plurality of documentation objects may document yet another marked segment, in another file other than the version of the source file <NUM>.

Optionally, new version of the source file <NUM> is an updated version of version of the source file <NUM>. Optionally, new version of the source file <NUM> comprises updated segment <NUM> which corresponds to, i.e. is equivalent to, marked segment <NUM> of version of the source file <NUM>. Optionally, new version of the source file <NUM> comprises one or more other updated segments, for example updated segment <NUM> corresponds to, i.e. is equivalent to, marked segment <NUM> of version of the source file <NUM>. Optionally, updated segment <NUM> is located at a line number in new version of the source file <NUM>, different from another line number in version of the source file <NUM> where marked segment <NUM> is located therein. Optionally, updated segment <NUM> is different from marked segment <NUM>. Optionally, new version of source file <NUM> comprises one or more unchanged documentation lines preceding, and additionally or alternatively following, updated segment <NUM>. Optionally, new version of source file <NUM> comprises one or more other changed documentation lines preceding, and additionally or alternatively following, updated segment <NUM>.

Optionally, documentation object <NUM> is not relevant to updated segment <NUM>, for example when documentation object <NUM> is outdated with respect to updated segment <NUM>. In such embodiments, an updated documentation object <NUM> is generated, documenting updated segment <NUM>. Optionally, documentation object <NUM> comprises a copy of updated segment 121A. Optionally, copy of updated segment 121A comprises the one or more unchanged documentation lines preceding, and additionally or alternatively following, updated segment <NUM>. Optionally, copy of updated segment 121A comprises the one or more other changed documentation lines preceding, and additionally or alternatively following, updated segment <NUM>.

Reference is now made also to <FIG>, showing a schematic block diagram of an exemplary apparatus <NUM>, according to some embodiments. In such embodiments, apparatus <NUM> comprises at least one hardware processor <NUM> connected to file version control system (VCS) <NUM>. Optionally, VCS <NUM> is a program executed by at least one other hardware processor, optionally connected to at least one hardware processor <NUM> via one or more digital communication network interface <NUM>. Optionally, VCS <NUM> is a program executed by at least one hardware processor <NUM>. Some examples of a VCS are git, Concurrent Versions System (CVS), Apache Subversion (SVN), PVCS Version Manager, IBM Rational, Visual SourceSafe, and Google Drive file versioning.

Optionally, one or more digital communication network interface <NUM> is connected to a local area network (LAN), for example an Ethernet network or a wireless network. Optionally, one or more digital communication network interface <NUM> is connected to a wide area network (WAN), for example the Internet.

For brevity, henceforth the term "processing unit" is used to mean "at least one hardware processor" and the terms are used interchangeably.

Optionally, processing unit <NUM> is connected to memory <NUM>, optionally storing program instructions. Optionally, memory <NUM> is a non-transitory computer readable storage medium, for example a read only memory (ROM). Optionally, memory <NUM> is a transitory computer readable storage medium, for example a random access memory (RAM).

Optionally, VCS <NUM> is connected to one or more non-volatile storage <NUM>, optionally for the purpose of storing a plurality of versions of a plurality of source files managed by VCS <NUM>. Some examples of a non-volatile storage are a hard disk drive (HDD), a solid state drive (SSD), a networked storage and a network connected storage. Optionally, processing unit <NUM> is connected to one or more non-volatile storage <NUM>, optionally for the purpose of storing a plurality of source documentation objects each documenting one of a plurality of marked segments each from one of the plurality of versions of the plurality of source files. Optionally, one or more non-volatile storage <NUM> is one or more non-volatile storage <NUM>.

Optionally, processing unit <NUM> is connected to at least one display device <NUM>, optionally for the purpose of displaying one or more of the plurality of documentation objects. Some examples of a display device are a computer screen, a smartphone screen and a monitor.

Optionally, apparatus <NUM> is a development environment, for example a software development environment. Optionally, the one or more of the plurality of documentation objects are displayed on at least one display device <NUM> as annotation of one or more of the plurality of versions of the plurality of source files displayed on at least one display device <NUM>, for example when apparatus <NUM> is a development environment.

In some embodiments described herewithin, apparatus <NUM> implements the following method, optionally executed, at least in part, by processing unit <NUM>.

Reference is now made also to <FIG>, showing a flowchart schematically representing an optional flow of operations <NUM> for updating documentation, according to some embodiments. In such embodiments, processing unit <NUM> executes flow of operations <NUM>. Optionally, in <NUM> processing unit <NUM> documents each of a plurality of marked segments in one of a plurality of source documentation objects. Optionally, each marked segment comprises at least part of one of a plurality of versions of one of a plurality of source files. In one example, the plurality of source files is a plurality of software program source files. Optionally, at least one of the plurality of source files is formatted according to a schema, for example a HyperText Markup Language (HTML) schema, or a schema of a test procedure. Optionally, each documentation object comprises a copy of the marked segment the documentation object documents.

Optionally, the plurality of source documentation objects is organized in at least one documentation file. Optionally, each of the at least one documentation file has a plurality of documentation versions. Optionally, the plurality of documentation versions of the at least one documentation file is managed by another VCS. Optionally, the other VCS is VCS <NUM>. Optionally, each documentation version of the at least one documentation file in the other VCS is associated with a version of at least one of the plurality of source files. Optionally, a set of documentation entries documenting one version of a source file are organized in one documentation file, optionally using a table. Optionally, each documentation object comprises additional metadata, optionally describing the version of the respective source file documented thereby and additionally or alternatively describing the marked segment documented thereby. For example, when each of the plurality of versions of the source file is associated with a digital signature value, a documentation object may comprise the digital signature value associated with the version of the source file documented thereby. Optionally, the digital signature value is a checksum value, optionally computed using a secure hash algorithm (sometimes known as a SHA value of the version of the source file), a textual description of the marked segment, and a path of the source file of the version of the source file when the plurality of source files is organized in a file directory. Optionally, the digital signature value is a checksum value computed for a plurality of versions of a plurality of source files modified in VCS <NUM> at an identified time, known also as a commit to VCS <NUM>.

Reference is now made again to <FIG>. For brevity, henceforth the term "version <NUM>" is used to refer to version of source file <NUM>, and the term "version <NUM>" is used to refer to new version of source file <NUM>, and the terms are used interchangeably respectively.

Reference is now made again to <FIG>. The plurality of source files is managed by VCS <NUM>. For example, VCS <NUM> may manage, among other files, version of source file <NUM>. In <NUM>, processing unit <NUM> identifies a new version of a source file of the plurality of source files, for example new version <NUM>. New version <NUM> was added to VCS <NUM> after version <NUM> had been added thereto. Optionally, processing unit <NUM> retrieves version <NUM> and additionally or alternatively version <NUM> from VCS <NUM>.

In <NUM>, processing unit <NUM> performs an identification of when updated segment <NUM> in new version <NUM> is different from marked segment <NUM>, where updated segment <NUM> is equivalent to marked segment <NUM>. Optionally the source file that version <NUM> and new version <NUM> are one of a plurality of versions thereof is organized in a plurality of lines. To perform the identification, processing unit <NUM> optionally computes a mapping between a plurality of line numbers of marked segment <NUM> in version <NUM> and a plurality of other line numbers of updated segment <NUM> in version <NUM>.

In some embodiments, processing unit <NUM> identifies updated segment <NUM> is different from marked segment <NUM> by applying documentation line changes. In such embodiments, processing unit <NUM> optionally executes the following optional method.

Reference is now made also to <FIG>, showing a flowchart schematically representing another flow of operations <NUM>. In <NUM> processing unit <NUM> applies a plurality of documentation line changes of copy of marked segment 111A to new version <NUM>. Optionally, processing unit <NUM> applies the plurality of documentation line changes using a patch application method of VCS <NUM>, for example git-apply when VCS <NUM> is a git VCS. Optionally, processing unit <NUM> identifies updated segment <NUM>, equivalent to marked segment <NUM>, when applying the plurality of documentation line changes to new version <NUM>.

In <NUM>, processing unit <NUM> optionally identifies a failure to apply the plurality of documentation line changes to new version <NUM>. Optionally, processing unit <NUM> uses the failure to identify in <NUM> that updated segment <NUM> is different from marked segment <NUM>.

In software development, the term "lint" refers to static software analysis of source code for programmatic and stylistic errors. As used herein, the terms "delint" and "applying lint" refer to removal from a text of one or more characters that do not change semantics of the text and thus may be ignored when comparing to another text for purposes of documentation. The term "lint characters" refers to such characters that do not change semantics of the text. Some examples of a lint character are a semicolon, a comma, a space, a new line character, a tab character, a form feed character, a carriage return character, and a vertical tab character. In some cases, applying lint to a text comprises replacing single quotes by double quotes or by back-quotes. In some other cases, applying lint to a text comprises replacing double quotes by single quotes or by back-quotes. In yet some other cases, applying lint to a text comprises replacing back-quotes by single quotes of back double quotes.

Reference is now made again to <FIG>. In response to the identification in <NUM>, in <NUM> processing unit <NUM> classifies updated segment <NUM> as one of a set of change classification. Some examples of a change classification include, but are not limited to: "change to lint-characters", "change to an inner block", "updatable single line change", "no change", "change to context", and "non-updatable change". Optionally, some change classifications indicate an ability to automatically update related documentation. Some examples of updatable changes include, but are not limited to, "change to lint-characters", "change to an inner block", and "updatable single line change".

Processing unit <NUM> classifies updated segment <NUM> according to one or more differences identified between updated segment <NUM> and copy of marked segment 111A.

Reference is now made also to <FIG>, showing a flowchart schematically representing an optional flow of operations for classification <NUM>, according to some embodiments. In such embodiments, to classify updated segment <NUM>, in <NUM> processing unit <NUM> computes one or more source line changes between new version <NUM> and version <NUM>. Optionally, to compute the one or more source line changes, processing unit <NUM> computes a mapping between a plurality of line numbers of marked segment <NUM> in version <NUM> and another plurality of line numbers of updated segment <NUM> in version <NUM>. Optionally, processing unit <NUM> computes the one or more source line changes by applying a compare method, for example Myers Diff algorithm. Optionally, the compare method is executed via VCS <NUM>. Optionally, in <NUM>, processing unit <NUM> computes the change classification by analyzing the one or more documentation line changes of copy of marked segment 111A and the one or more source line changes to identify the one or more differences between updated segment <NUM> and copy of marked segment 111A.

Reference is now made also to <FIG>, showing a flowchart schematically representing another optional flow of operations for classification <NUM>, according to some embodiments. In such embodiments, in <NUM> processing unit <NUM> classifies each of the one or more documentation line changes as one of a set of line-change classifications. Some examples of a line-change classification are: ADDITION, DELETION, UPDATE, CONTEXT, and NO CHANGE. Optionally, in <NUM> processing unit <NUM> analyzes the one or more documentation line changes and the one or more source line changes to identify the one or more differences between updated segment <NUM> and copy of marked segment 111A, to produce a plurality of line-change classifications.

In <NUM>, processing unit <NUM> optionally computes the change classification by analyzing the plurality of line-change classifications.

Optionally, before classifying updated segment <NUM> processing unit <NUM> generates a dynamic patch file using a set of description objects documenting one or more marked segments in file version <NUM>. Optionally, the dynamic patch file comprises an array of hunk containers, each computed using one of the set of description objects and organizing one or more of: the plurality of line-change classifications, the one or more documentation line changes, and the one or more source line changes.

Reference is now made again to <FIG>. In <NUM>, processing unit <NUM> generates updated source documentation object <NUM>. Optionally, processing unit <NUM> generates updated source documentation object <NUM> subject to the change classification computed in <NUM> being a member of a set of updateable changes. Processing unit <NUM> generates updated documentation object <NUM> by modifying copy of marked segment 111A according to the changes classification and the one or more differences.

Optionally, <NUM> and <NUM> are combined, and copy of marked segment 111A is modified while classifying updated segment <NUM>. Reference is now made also to <FIG>, showing pseudo-code representing an optional flow of operations <NUM> for modifying documentation, according to some embodiments. As used in henceforth, the term "inner context" refers to one or more lines of copy of marked segment 111A which are changed in updated segment <NUM> and each comprise at least one character that is not a whitespace character. In addition, as used henceforth, the terms "side A" and "side B" refer respectively to item A and item B of a file comparison method, for example, Myer Diff Algorithm. Optionally, side A refers to version <NUM> and side B refers to updated version <NUM>. In such embodiments, method <NUM> is used when classifying updated segment <NUM> as "change to lint-characters". Optionally, analyzing the plurality of line-change classifications comprises applying lint to copy of marked segment 111A and the one or more source line changes, optionally producing copy of updated segment 121A, optionally for producing updated documentation object <NUM>.

Reference is now made also to <FIG>, showing pseudo-code representing another optional flow of operations <NUM> for modifying documentation, according to some embodiments. In such embodiments, method <NUM> is used when classifying updated segment <NUM> as "change to an inner block". Optionally, analyzing the plurality of line-change classifications comprises replacing one or more lines of copy of marked segment 111A with one or more other lines of updated segment <NUM>, optionally producing copy of updated segment 121A, optionally for producing updated documentation object <NUM>.

Reference is now made also to <FIG>, showing pseudo-code representing yet another optional flow of operations <NUM> for modifying documentation, according to some embodiments. In such embodiments, method <NUM> is used when classifying updated segment <NUM> as "updatable single line change". Optionally, analyzing the plurality of line-change classifications comprises replacing one line of copy of marked segment 111A with an equivalent line of updated segment <NUM>, optionally producing copy of updated segment 112A, optionally for producing updated documentation object <NUM>. Optionally, method <NUM> is applied after failing to classify updated segment <NUM> as "change to an inner block".

Optionally, generating updated documentation object <NUM> additionally, or alternatively, comprises processing unit <NUM> modifying copy of marked segment 111A according to the one or more unchanged documentation lines preceding, and additionally or alternatively following, updated segment <NUM>. Optionally, generating updated documentation object <NUM> additionally, or alternatively, comprises processing unit <NUM> modifying copy of marked segment 111A according to the one or more other changed documentation lines preceding, and additionally or alternatively following, updated segment <NUM>.

Optionally, generating updated documentation object <NUM> additionally, or alternatively, comprises processing unit <NUM> modifying one or more line numbers of copy of marked segment 111A in version <NUM> according to one or more other line numbers of updated segment <NUM> in version <NUM>.

It may be that a source file's name was changed. Optionally, classifying updated segment <NUM> comprises identifying a file name of new version <NUM> is different from another file name of version <NUM>, i.e. identifying a rename. Optionally, identifying the file name of new version <NUM> is different from the other file name of version <NUM> comprises identifying a plurality of removed files removed from VCS <NUM> and a plurality of added files added to VCS <NUM>. Optionally, identifying the rename further comprises organizing the plurality of removed files and the plurality of added files in pairs, each comprising one of the plurality of added files and one of the plurality of removed files. Optionally, identifying the rename further comprises computing a plurality of similarity scores, one for each pair, and indicative of a degree of similarity between the pair. Optionally, a pair having a similarity score exceeding a threshold similarity score is considered a rename of a file.

It may be that the source file was moved in a file directory according to which the plurality of source files is organized. Optionally, classifying updated segment <NUM> comprises identifying a file path of new version <NUM> is different from another file path of version <NUM>. When source documentation object <NUM> comprises the other file name of version <NUM> and additionally or alternatively the other file path of version <NUM>, updated documentation object <NUM> is optionally modified using the file name of version <NUM> and additionally or alternatively the file path of version <NUM>.

Optionally, documentation object <NUM> comprises a textual description describing marked segment <NUM>. Reference is now made also to <FIG>, showing a flowchart schematically representing an optional flow of operations <NUM> for updating documentation text, according to some embodiments. In such embodiments, in <NUM> processing unit <NUM> identifies one or more tokens present in the textual description. Optionally, processing unit <NUM> identifies the one or more tokens in the one or more differences identified between updated segment <NUM> and copy of marked segment 111A. For example, when the source file is a source code file of a software program, a token may be a function name or a name of an argument of a function. Optionally, a token is a file name or a module name. In <NUM>, processing unit <NUM> optionally identifies in the one or more differences one or more updated tokens, equivalent to the one or more tokens identified in <NUM>. Optionally, to identify the one or more updated tokens, processing unit <NUM> links at least one filename identified in the documentation text with an object describing a version of the plurality of versions of the source file. Optionally, when a source file is renamed, processing unit <NUM> updates the object according to a new filename of the source file. In <NUM>, processing unit <NUM> optionally generates updated documentation object <NUM> by replacing in the textual description the one or more tokens with the one or more updated tokens.

When the change classification is "non-updatable change", processing unit <NUM> optionally generates updated documentation object <NUM> using copy of marked segment 111A and by marking copy of marked segment 111A as obsolete, optionally in updated documentation object <NUM>.

When the change classification is "no change" or "change to context", processing unit <NUM> optionally generates updated documentation object <NUM> using copy of marked segment 111A. Optionally, processing unit <NUM> associates documentation object <NUM> with new version <NUM>.

In <NUM>, processing unit <NUM> optionally documents new version <NUM> with updated source documentation object <NUM>, for example by adding to updated documentation object <NUM> a new digital signature value computed using new version <NUM>.

Optionally, processing unit <NUM> identifies in VCS <NUM> one or more other new versions of the source file of version <NUM>, where each of the one or more other new versions was added to VCS <NUM> after version <NUM> and before new version <NUM>.

Optionally, processing unit <NUM> produces a sequence of versions of the source file by organizing the one or more other new versions in ascending order of addition to the VCS. Optionally, processing unit <NUM> generates updated documentation object <NUM> in a plurality of iterations, each time using two consecutive files in the sequence of versions. Optionally, in each of the plurality of iterations, processing unit <NUM> repeats <NUM>, <NUM> and <NUM>, using a consecutive version of the source file, immediately following version <NUM> in the sequence of versions, as new version <NUM> in a first iteration of the plurality of iterations. Optionally, in each of the plurality of iterations, processing unit <NUM> uses the consecutive version as version <NUM> in a next iteration of the plurality of iterations. Optionally, in each of the plurality of iterations, processing unit <NUM> uses updated source documentation object <NUM> as documentation object <NUM> in the next iteration.

In some embodiments, a software program product comprises memory <NUM> storing program instructions for executing method <NUM>. Optionally, processing unit <NUM> executes the program instructions from memory <NUM>. Optionally, the software program product is a plug-in module for an integrated development environment (IDE).

Reference is now made also to <FIG> and <FIG>, showing exemplary screenshots of a development environment, according to some embodiments. With reference to <FIG>, in such embodiments, when a user selects one or more versions of one or more source files, screenshot <NUM> is displayed to show marked segment <NUM>, marked segment <NUM> and marked segment <NUM> of the one or more versions of the one or more source files. Optionally, marked segment <NUM>, marked segment <NUM> and marked segment <NUM> are from one version of one source file. Optionally, screenshot <NUM> is displayed on display <NUM>, optionally by processing unit <NUM>. Optionally, a first source documentation object associated with marked segment <NUM> comprises documentation text <NUM>, in this example including the text "In this step we define the value in config. Optionally, processing unit <NUM> displays documentation text <NUM> as an annotation to marked segment <NUM>. Optionally, indication <NUM> shows that the first source documentation object is up-to-date and relevant to marked segment <NUM>.

Similarly, indication <NUM> optionally shows that a second source documentation object, associated with marked segment <NUM>, is up-to-date and relevant to marked segment <NUM>. Further similarly, indication <NUM> optionally shows that a third source documentation object, associated with marked segment <NUM>, is up-to-date and relevant to marked segment <NUM>.

When one or more new versions of the one or more source files are available, processing unit <NUM> optionally executes method <NUM>. For example, in the one or more new versions marked segment <NUM> may be modified to produce updated segment 801A and marked segment <NUM> may be modified to produce updated segment 803A. Optionally marked segment <NUM> is unmodified. Optionally, an outcome of executing method <NUM> is a first updated source documentation object associated with updated segment 801A comprising an indication of a failure to automatically update the documentation. Optionally, another outcome of executing method <NUM> is a second updated source documentation object associated with marked segment <NUM> comprising a copy of marked segment <NUM> copied from the second source documentation object, and a third updated source documentation object associated with updated segment 803A comprising an indication that third updated source documentation object comprises a copy of updated segment 803A, automatically generated by execution of method <NUM>.

With reference to <FIG>, after execution of method <NUM>, in such embodiments when the user selects the one or more new versions of the one or more source files, screenshot 800A is displayed to show updated segment 801A, marked segment <NUM> and updated segment 803A of the one or more new versions of the one or more source files. Optionally, indication <NUM> now shows that the first updated source documentation object is no longer up-to-date with reference to updated segment <NUM>.

On the other hand, in screenshot 800A indication <NUM> optionally shows that the second updated source documentation object, associated with marked segment <NUM>, is up-to-date and relevant to marked segment <NUM>. In addition, in screenshot 800A, indication <NUM> optionally shows that the third updated source documentation object, associated with marked segment <NUM>, was automatically generated and is up-to-date and relevant to updated segment 803A. It should be noted that in this example a change in line number between marked segment <NUM> and updated segment 803A does not prevent automatic generation of the third updated source documentation object to be up-to-date and relevant to updated segment 803A. In addition, in this example a change in file name does not prevent automatic generation of the third updated source documentation object to be up-to-date and relevant to updated segment 803A.

The terminology used herein was chosen to best explain the principles of the embodiments, the practical application or technical improvement over technologies found in the marketplace, or to enable others of ordinary skill in the art to understand the embodiments disclosed herein.

Any particular embodiment may include a plurality of "optional" features unless such features conflict.

Throughout this application, various embodiments may be presented in a range format. It should be understood that the description in range format is merely for convenience and brevity and should not be construed as an inflexible limitation on the scope of embodiments.

It is appreciated that certain features of embodiments, which are, for clarity, described in the context of separate embodiments, may also be provided in combination in a single embodiment. Conversely, various features of embodiments, which are, for brevity, described in the context of a single embodiment, may also be provided separately or in any suitable subcombination or as suitable in any other described embodiment.

Claim 1:
A computer-implemented method comprising:
executing a code in a development environment comprising a file version control system, VCS, (<NUM>) for:
documenting (<NUM>) each of a plurality of marked segments (<NUM>) in one (<NUM>) of a plurality of source documentation objects associated therewith, each marked segment comprising at least part of one (<NUM>) of a plurality of versions of one of a plurality of source files managed by the VCS, where each source documentation object comprises a copy of the marked segment (111A) documented thereby, organized as a documentation patch instructing removal of the marked segment from the version of the source file;
identifying (<NUM>) in the VCS a new version (<NUM>) of a source file of the plurality of source files, where the new version was added to the VCS after a version (<NUM>) of the source file having a marked segment (<NUM>) documented by a source documentation object (<NUM>) of the plurality of source documentation objects;
performing (<NUM>) an identification of when an updated segment (<NUM>) in the new version of the source file, equivalent to the marked segment, is different from the marked segment, by:
applying the copy of the marked segment as a documentation patch to the new version of the source file; and
identifying the updated segment is different from the marked segment when application of the documentation patch fails; and
in response to the identification:
classifying (<NUM>) the updated segment as one of a set of change classifications according to
one or more differences identified between the updated segment and the copy of the marked segment; and
subject to the change classification being a member of a set of updatable changes, generating (<NUM>) an updated source documentation object (<NUM>) by modifying the copy of the marked segment (121A) according to the change classification and the one or more differences;
wherein the plurality of source documentation objects is organized in at least one documentation file each having a plurality of documentation versions;
wherein the plurality of documentation versions of the at least one documentation file is managed by another VCS; and
wherein each documentation version of the at least one documentation file in the other VCS is associated with a version of at least one of the plurality of source files in the VCS.