Add documentation to public functions

[vlinkz]

Currently, none of the public functions have proper documentation comments, so the generated docs are empty.
See: https://docs.rs/nix-editor/latest/nix_editor/

Documentation is needed describing what each function does, as well as providing some examples.
Getting started: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html

[Adelakin-Adewumi]

I will love to work on this documentation. Kindly assign it to me.

[vlinkz]

Sounds great! I've assigned you the issue. Since the code is a bit messy I'd say the most important things to document at the moment are.

From read.rs:

• pub fn readvalue
• pub fn getarrvals
• pub fn getwithvalue

From write.rs:

• pub fn write
• pub fn addtoarr
• pub fn rmarr
• pub fn deref

From parse.rs

• pub fn collectattrs

A lot of it is pretty confusing, so please let me know if you have any questions! Also don't feel obligated to do all since there is a lot and the code is very convoluted. A lot of the code ties heavily in with the rnix crate: (https://docs.rs/rnix/0.10.2/rnix/), so most non-standard rust types are coming from there

[Adelakin-Adewumi]

Sounds great! I've assigned you the issue. Since the code is a bit messy I'd say the most important things to document at the moment are.

From read.rs:

• pub fn readvalue
• pub fn getarrvals
• pub fn getwithvalue

From write.rs:

• pub fn write
• pub fn addtoarr
• pub fn rmarr
• pub fn deref

From parse.rs

• pub fn collectattrs

A lot of it is pretty confusing, so please let me know if you have any questions! Also don't feel obligated to do all since there is a lot and the code is very convoluted. A lot of the code ties heavily in with the rnix crate: (https://docs.rs/rnix/0.10.2/rnix/), so most non-standard rust types are coming from there

Okay, I'd let you know if I have any question. I want to go through it. Thank you

[Adelakin-Adewumi]

Hi Victor, Thank you for having me join with your documentation. I'd like to ask what the project about. What you are trying to achieve, this will help with the documentation. You know that I need to get the concept behind the project so I don't write a different things. I hope you understand my question. Kind regards, Adewumi.

…

On Fri, Sep 30, 2022, 21:05 Victor Fuentes ***@***.***> wrote: Sounds great! I've assigned you the issue. Since the code is a bit messy I'd say the most important things to document at the moment are. From read.rs <https://github.com/vlinkz/nix-editor/blob/main/src/read.rs>: - pub fn readvalue <https://github.com/vlinkz/nix-editor/blob/main/src/read.rs#L15> - pub fn getarrvals <https://github.com/vlinkz/nix-editor/blob/main/src/read.rs#L43> - pub fn getwithvalue <https://github.com/vlinkz/nix-editor/blob/main/src/read.rs#L80> From write.rs <https://github.com/vlinkz/nix-editor/blob/main/src/write.rs>: - pub fn write <https://github.com/vlinkz/nix-editor/blob/main/src/write.rs#L22> - pub fn addtoarr <https://github.com/vlinkz/nix-editor/blob/main/src/write.rs#L269> - pub fn rmarr <https://github.com/vlinkz/nix-editor/blob/main/src/write.rs#L343> - pub fn deref <https://github.com/vlinkz/nix-editor/blob/main/src/write.rs#L414> From parse.rs <https://github.com/vlinkz/nix-editor/blob/main/src/parse.rs> - pub fn collectattrs <https://github.com/vlinkz/nix-editor/blob/main/src/parse.rs#L109> A lot of it is pretty confusing, so please let me know if you have any questions! Also don't feel obligated to do all since there is a lot and the code is very convoluted. A lot of the code ties heavily in with the rnix crate: (https://docs.rs/rnix/0.10.2/rnix/), so most non-standard rust types are coming from there — Reply to this email directly, view it on GitHub <#14 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AOYS2ATTYA5WL5HBHOR6JV3WA5BXVANCNFSM6AAAAAAQYCJGFQ> . You are receiving this because you were assigned.Message ID: ***@***.***>

[vlinkz]

Of course!

Basically, this project is a tool called nix-editor which can be used to modify .nix files programmatically while maintaining valid syntax. .nix files are primarily used by NixOS and the Nix package manager to declaratively build packages and configurations (see: https://nixos.org/). The primary usage of this tool is so that other programs can modify .nix files imperatively, some examples of tools using this are Nix Software Center and NixOS Configuration Editor. The tool also has a command line utility so that even programs not written in rust can take advantage of the functionality.

Here's a quick example of how it could be used, say we have a file default.nix containing the following:

{
  value1 = "Hello";
}

If we want to add another value to this attribute set, we could use nix-editor as follows:

nix-editor default.nix  value2 -v '"world!"' -o default.nix

Now the file default.nix would contain

{
  value1 = "Hello";
  value2 = "world!";
}

While this tool does have a command line help screen, since there is no documentation for the backend function, trying to implement it into other rust programs can be difficult at the moment. The functions don't need very long descriptions, just a simple description or sentence should do, for example:
pub fn readvalue

/// Returns the value of the query from the given input string of `.nix` file text `f` and query `query`, 
pub fn readvalue(f: &str, query: &str) -> Result<String, ReadError> {

[Adelakin-Adewumi]

Of course!

Basically, this project is a tool called nix-editor which can be used to modify .nix files programmatically while maintaining valid syntax. .nix files are primarily used by NixOS and the Nix package manager to declaratively build packages and configurations (see: https://nixos.org/). The primary usage of this tool is so that other programs can modify .nix files imperatively, some examples of tools using this are Nix Software Center and NixOS Configuration Editor. The tool also has a command line utility so that even programs not written in rust can take advantage of the functionality.

Here's a quick example of how it could be used, say we have a file default.nix containing the following:

{
  value1 = "Hello";
}

If we want to add another value to this attribute set, we could use nix-editor as follows:

nix-editor default.nix  value2 -v '"world!"' -o default.nix

Now the file default.nix would contain

{
  value1 = "Hello";
  value2 = "world!";
}

While this tool does have a command line help screen, since there is no documentation for the backend function, trying to implement it into other rust programs can be difficult at the moment. The functions don't need very long descriptions, just a simple description or sentence should do, for example: pub fn readvalue

/// Returns the value of the query from the given input string of `.nix` file text `f` and query `query`, 
pub fn readvalue(f: &str, query: &str) -> Result<String, ReadError> {

okay, thank you. I will do a PR, i hope you will like it and merge it.

[axelkar]

Hi! Any progress on this?