Add documentation for all data structures and algorithmic functions

[faheel]

Add a README to each directory containing proper documentation for algorithms or data structures in that directory.

[sriram-25]

What all should the documentation contain? For eg. Time Complexity,Working of the Algorithm? @faheel

[faheel]

For now the documentation will not include the working details of the algorithm but only information about the "interface" of various functions, i.e. about:

• what the function does,
• its inputs,
• its output (return value), if any,

along with (wherever necessary),

• time complexity,
• space complexity.

The inputs, variables and output will have their type, name and a single line description. The time and space complexity will be of the best and worst cases (and average case too, if necessary).

For example, for Kadane.cpp the documentation could look like:

---

maximumSubarray

<description of what the function does in 1-2 lines>

Input

• values

  Type: const vector<int> &

  <description in 1-2 lines>

Output

• tuple of maxSum, start, end

  Type: tuple<int, size_t, size_t>

  <description of maxSum in 1-2 lines> <description of start in 1-2 lines> <description of end in 1-2 lines>

Time complexity

• Worst case

  O(N), where N is the size of values

• Best case

  O(N), where N is the size of values

---

Markdown for the above documentation:

## `maximumSubarray`
<description of what the function does in 1-2 lines>

### Input
- #### `values`
  Type: `const vector<int> &`

  <description in 1-2 lines>

### Output
- #### tuple of `maxSum`, `start`, `end`
  Type: `tuple<int, size_t, size_t>`

  <description of `maxSum` in 1-2 lines>
  <description of `start` in 1-2 lines>
  <description of `end` in 1-2 lines>

### Time complexity
- #### Worst case
  _O_(**N**), where **N** is the size of `values`
- #### Best case
  _O_(**N**), where **N** is the size of `values`

[faheel]

Issue #74 is now closed

[faheel]

This task can be automated using Doxygen.

[stale[bot]]

This issue has been automatically marked as inactive because it has not had recent activity. It will be closed in 15 days if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as inactive because it has not had recent activity. It will be closed in 15 days if no further activity occurs. Thank you for your contributions.

[ghost]

I can definitely get start on this, if it's still open.

[chhawip]

@faheel is this issue still up for grab? I can definitely contribute to it.

[faheel]

@safderareepattamannil and @itz-me9 Sorry for the late response. Yes, this issue is up for grabs and your contributions are welcome.

[LuisFerTR]

For now the documentation will not include the working details of the algorithm but only information about the "interface" of various functions, i.e. about:

• what the function does,
• its inputs,
• its output (return value), if any,

along with (wherever necessary),

• time complexity,
• space complexity.

The inputs, variables and output will have their type, name and a single line description. The time and space complexity will be of the best and worst cases (and average case too, if necessary).

For example, for Kadane.cpp the documentation could look like:

maximumSubarray

<description of what the function does in 1-2 lines>

Input

• values

  Type: const vector<int> & <description in 1-2 lines>

Output

• tuple of maxSum, start, end

  Type: tuple<int, size_t, size_t> <description of maxSum in 1-2 lines> <description of start in 1-2 lines> <description of end in 1-2 lines>

Time complexity

• Worst case

  O(N), where N is the size of values

• Best case

  O(N), where N is the size of values

Markdown for the above documentation:

## `maximumSubarray`
<description of what the function does in 1-2 lines>

### Input
- #### `values`
  Type: `const vector<int> &`

  <description in 1-2 lines>

### Output
- #### tuple of `maxSum`, `start`, `end`
  Type: `tuple<int, size_t, size_t>`

  <description of `maxSum` in 1-2 lines>
  <description of `start` in 1-2 lines>
  <description of `end` in 1-2 lines>

### Time complexity
- #### Worst case
  _O_(**N**), where **N** is the size of `values`
- #### Best case
  _O_(**N**), where **N** is the size of `values`

I can help with this, is still open? Any changes about what documentation should contain?

[alxmjo]

@LuisFerTR Great! See the readme for backtracking for a guide for how to implement this.

In order to avoid duplicate work, though, please create a new issue describing which section of this you'll take (number_theory, sorting, etc.).

I'm going to leave this issue as Up for grabs since different people can take different parts of it (by opening specific issues referencing what they'd like to do).

[100sarthak100]

@faheel is this issue still up for grabs? I can add documentation for dynamic programming.

[alxmjo]

@100sarthak100 Great! Just create a new issue for that particular section, as @LuisFerTR has done.

[ghost]

Hi, I'm trying to cover the documentation for sorting algorithms. I want to include an example for Usage in each algorithm, but i don't understand how to set the value of order and ShowState. These input functions are defined in the utils file, could you guide me as to how these are supposed to be called from a .cpp file.

Usage

c++vector<int> nums{4, 6, 1, 23, 2};
bubblesort(nums, 1, true);

Is this correct?

On Sun, 14 Jun 2020 at 08:03, Alex Johnson [email protected] wrote:

Great! Feel free to open a PR.

On Jun 13, 2020, at 6:37 PM, ivy-2000 [email protected] wrote:

Hi! I took a step further and added documentation to my forked repo, since the issue is up for grabs could I open a MR? @alxmjo < https://github.com/alxmjo> I understand if the issue needs to be assigned first.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub < https://github.com/ProAlgos/ProAlgos-Cpp/issues/59#issuecomment-643705352>, or unsubscribe < https://github.com/notifications/unsubscribe-auth/AAMUKKXDWFDBOJCTESLLS7TRWQSVZANCNFSM4DNFINVQ .

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/ProAlgos/ProAlgos-Cpp/issues/59#issuecomment-643708939, or unsubscribe https://github.com/notifications/unsubscribe-auth/AOR4INRFR3IF53VZB6IZ2XDRWQZJFANCNFSM4DNFINVQ .

[alxmjo]

Hi @ivy-2000. You are on the right track. More specifically, the algorithms in this project are implemented as header files (ending in .hpp). These algorithms are then called from test files (ending in .cpp).

The complicating factor with the sorting algorithms is that we have one test file for all sorting algorithms (sorting.cpp) since we can test all of our sorting algorithms in the same way (and so don't need different .cpp files for each sorting algorithm).

But none of that should concern you. To call bubble_sort, for example, all you need to know is that the function takes three inputs:

1. A reference to the vector to be sorted
2. An integer indicating the order (increasing or decreasing)
3. A boolean indicating whether or not to show state.

Note that those last two parameters have default values (1 and false, respectively), so that one could call the function by just passing in a reference to the vector to be sorted and the function would "assume" (based on the default values) that you wanted it sorted increasing and without showing state.

If you want to play around with this a bit, try copying and importing bubble_sort.hpp into your own program and then calling bubble_sort() to sort your own vector. Create your own main.cpp (on your own desktop, for example) and do something like this:

#include "bubble_sort.hpp" // which you've copied from Algos-Cpp and put into the same directory as your main.cpp file

int main() {
    vector<int> nums{4, 6, 1, 23, 2};
    bubble_sort(nums, 1, true);
}

Playing around with it is probably the only way to really figure out what's going on.

[vanichitkara]

Is this issue still up for grab? I can work on it!

[alxmjo]

Is this issue still up for grab? I can work on it!

Yep!

[rishabhp99]

I would like to work on this if this issue is till up for grab.

[alxmjo]

I would like to work on this if this issue is till up for grab.

As long as there's documentation to be completed it's up for grabs. 🙂

[abarbee129]

I would love to work on the number theory documentation if it is still available.

[abarbee129]

Hey I have a small change to make and I would like to make a pull request. I know the mechanics, but I don't know the best practices. Additionally I'm very very new to open source. Is anyone willing to help me with the process.

[alxmjo]

@abarbee129 Definitely up for grabs. Read through our documentation and then let me know if you have any questions. 🙂

[abarbee129]

@alxmjo I tried to push a small typo change to origin but I got an error because permission was denied to me. Can you help me with that? The error says Permission to ProAlgos/ProAlgos-Cpp.git denied to abarbee129.

[alxmjo]

@alxmjo I tried to push a small typo change to origin but I got an error because permission was denied to me. Can you help me with that? The error says Permission to ProAlgos/ProAlgos-Cpp.git denied to abarbee129.

You should be pushing to your own fork, not directly to ProAlgos. What exact commands did you use to try to push?

[vedsom]

@faheel, @alxmjo I want to add documentation for linked list under hactoberfest 2022

[Arna03v]

Hi @alxmjo @faheel, i noticed there is no documentation for Radix sort, can i go ahead and work on it?