Missing essential examples

[pauelm]

This looks like some interesting code, and might lead to something promising, but how are the methods supposed to be called? For example, how are the args supposed to be structured in the main execution code, where there are 3 different scenarios? I could not find any documentation or real, actual examples. Without that, users are left to wide-open, unending guessing, starting with proper method calling and input for "args" below:

if (args.Length != 3) { throw new ArgumentException(nameof(args)); }

        var file = new JpegImage
        {
            Bytes = File.ReadAllBytes(args[0]),
            Width = int.Parse(args[1]),
            Height = int.Parse(args[1])
        };

        var bytes = DocLib.Instance.JpegToPdf(new[] { file });

        File.WriteAllBytes("file.pdf", bytes);

[Modest-as]

Are you talking about example not being clear what argument positions get passed where into the DocLib methods? Because DocLib interface has documentation on all public methods bundled with the nuget package and in this case JpegToPdf takes a well structured input object so there is no confusion.

[pauelm]

Thanks for the quick response. I was not referring specifically to DocLib. (However, I went back and double-checked the nuget package and confirmed that there is not any documentation included in the package.) As stated in my message, I am referring to missing examples as to how the "args" parameter is to be structured, specifically in "PdfToImage". Without any example on how the value of args needs to be structured so that it is passed in properly, then the code is obviously not going to do anything except generate a runtime error, right? This also happened to be exactly the same situation as the code for JpegToPdf that you specifically referenced.

On the JpegToPdf implementation, I should point out that the latest and greatest code that I pulled down from the repo would not even build. If it doesn't build, then obviously, it cannot be executed and tested. The initial issue I discovered as to why the code would not build is that the "JpegImage" object you attempt to create was not recognized. The reason why it was not recognized is because a vital reference was missing. After I dug around and located it in the solution, I resolved the reference issue by adding "using Docnet.Core.Editors" to the main Program.cs file. If you attempted to build this project with this same version of code, you would run into the exact same problem. It also means that there is no way possible that this specific version of code could have passed a BVT. (I am certainly not familiar with the set of class libraries in the solution, but this was actually a pretty quick and easy fix.)

Also, I am talking about "example1.cs", "example2.cs", "example3.cs". The methods in these classes are implementation code, and also does not provide any examples HOW any of these "examples" would actually be called. If there is no example code on how they are called, nor any documentation that is clear on how you would actually call specific, methods that are essential for proper execution of core functionality, then it leaves a lot of guesswork.

My main goal is working through methods that can be used for simply converting each page in a pdf file to individual png files, hence my interested in locating some libraries that can effectively perform this task, which I will then modify for my specific needs. After the png files are created for each page in the PDF, I will then enumerate through png's associated with each pdf file, then create a pptx (per pdf file), if that makes sense.

[Modest-as]

Firstly, the documentation on DocLib is there, the XML is read properly by IntelliSense in my VS, just double checked.

Secondly I have not heard about anyone having troubles building the solution before, do you mean that you can not build the library or just an example project? I am confused what the problem here is, is the library interface not intuitive in your opinion or you do not know how examples should work? In case of the latter they are just quick and dirty examples how one would use the library, the fact that args are not explained there is inconsequential since I am not building a CLI, it should just showcase how to manage the lifetime of the library, how to convert a bitmap to a usable image etc.

[Modest-as]

I would however welcome PRs with more examples that we can showcase how to use the library so there are no confusions like these in the future.

[pauelm]

When I pulled down the latest and greatest version out of the repo, opened it up in VS, it would NOT build. This is before I attempt to write some test calls to any of the methods in the project. When this happens, it is more often the case that a simple nuget package is missing or some other assembly is not in the local instance of the project, which is completely understandable, and is typically a quick and easy fix. However, this was not a case of a missing assembly or nuget package. Before I could add a test project, write up some method calls to test (and create my own errors, which I would anticipate doing along the way, until I resolved them and fully test out my code, etc.), there were showstopping errors in the original solution, even after all the assemblies and nuget packages were verified.

For example, with the latest and greatest version at the time was pulled down from the repo, the line "var file = new JpegImage" throws an error, because the solution would not compile. If the solution will not compile, then it will not build. If it will not build, then there is no possible way for the tool to work, right? It also means that there is no way for this version of the code in the repo could have been tested, because of this blocking bug.

I found that the culprit was a missing reference call in the Program.cs file. Once I added "using Docnet.Core.Editors" reference in the file, then it resolved the bug. However, without this actual change in the original code, then there is no way for the code in the project to have been tested. If the code cannot be tested, then there is no way to know if any of the methods would actually work. In other words, with any code I add to test any of the proposed examples, how is my code going to compile and execute if the underling projects in the solution currently does not even successfully compile and build?

After I resolved the issue and started some initial testing, I realized that the "example" calls to the example.cs class methods are theoretical, and not actually examples. This is because there is just a calling method in main that does not include calls that pass in arguments to "args" parameter, that are essential for the code to even execute without generating runtime errors. Even after resolving the compile and build issues by including a reference call that was missing, and that is also mandatory so that the project will compile and build, the solution still cannot execute as-is, because additional errors are thrown, due to missing "args" parameter. While it is essential to see examples on how to use any of the methods in the solution, the actual solution itself needs an "example" (in the "args" parameter, at a minimum), in order for the solution to actually execute without runtime errors.

Keep in mind that showstoppers like this is all before another developer attempts to actually use any of the methods for testing, and it also means that there is no way to run any type of example at this point. This is also where a developer is attempting to leverage functionality from a solution they are not intimately familiar with immediately after downloading it, from a solution that also does not compile or build, and that apparently has no documentation or examples on how it actually works, even though the code I reviewed in the solution looks promising.

If there was actually a working example, then I could use that for testing the solution's functionality, with additional test scenarios for my specific needs, from a separate test project, leaving the core DocNet solution unchanged. The key methods I am looking for working examples is passing in an existing PDF file, enumerating through the file and creating an individual PNG file for each page in the PDF.

[Modest-as]

I can assure you that the latest master compiles, builds and tests pass on all 3 platforms https://github.com/GowenGit/docnet/actions/runs/96585842

[Modest-as]

Furthermore I have just pulled the repo to a completely blank environment and both example projects manage to build with no issues:

If you are still having any issues I suggest providing some screenshots, logs and stack traces instead.

[pauelm]

I promise I am not crazy. :-) I just did another fresh pull from the repo, and attempted to build Docnet.Core solution. Attached is the list with numerous build errors that are thrown.

Also, the "ImageToPdf" solution directly from the repo does not build, due to an error on line 21: var file = new JpegImage

I confirmed this same issue after downloading the solution again. It did not recognize the "JpegImage" object, and after locating it, added a reference to Docnet.Core.Editors, it now compiles and builds just fine. However, if you attempt execute it, it obviously fails because there is no specification for "args" to pass into the main code execution. This is one of the main outstanding issues. It shows that even this "example" needs an adequate example in order for it to execute properly.

As for the "pdf-to-image" solution, it builds just fine right out of the repo. However, while there are some "Example.cs" class files there, the end result is essentially the same as the "ImageToPdf" solution, as it too needs actual examples in order for it to execute properly.

In attempt to resolve the build issues specifically with the main "Docnet" solution, I am re-applying VS update 15.9 to see if it may resolve some of these issues, and will report back status when this is done, and I test this solution again.

[Modest-as]

hmm, do you have .net core 3.1 sdk installed and setup on your system?

[pauelm]

Update:

After re-applying VS update 15.9, I still have the same build errors. Just for the time being to shield / reduce some of the errors, I temporarily unloaded the test projects in the solution (Docnet.Tests.Integration and Docnet.Tests.Unit), to help isolate some of the issues and focus just on the main Docnet.Core project in the solution.

I did confirm that I have .net core 3.1 sdk installed. On a side note, the Docnet.Core project is currently configured to target the .Net Standard 2.0 framework. Also, many of the errors, some related to other components such as Microsoft.CodeQuality.CSharp.Analyzers.dll, these components are currently complaining that such components rely on the 2.0 version of the "netstandard" assembly. Let me know if there is a different framework version that I should change any of the projects, and I will try compiling and building under those target frameworks, and see if it eliminates the build errors.

Seems odd that these other assemblies are complaining about the netstandard.dll assembly needing to be version 2.0, especially when I can see that the Docnet.Core project already has it, and it is currently linked to version 2.0 for that assembly.

On a side note, the separate "pdf-to-Image" solution compiles and builds just fine, but it will not run because it is missing arguments in the mainline Program.cs.

[Modest-as]

This is indeed strange, most of the error seem to be because you can no resolve code analyzers, I am not sure what kind of dependencies you have and have not installed on your system but you can see in the windows CICD branch here https://github.com/GowenGit/docnet/runs/647640540?check_suite_focus=true that on every fresh windows environment with .Net Core SDK Version: 3.1.201 everything compiles and tests pass just fine. If you use vscode you can try opening the project in a .NET Core 3.1 docker development container to eliminate any possibilities of dependencies on your system not acting as they should and see if that work. Again, it compiles and works on numerous machines that I have tested it on be it windows/ios/linux. It would be interesting to know why it is not the case on yours. Regarding examples they were built as a CLI examples, they take in command line arguments, if you run them from VS without specifying the command line args it will not work, you either need to open project settings and specify your args in the debug tab or build the proect and run exe as a standalone in your console.

[pauelm]

Yes, it is definitely strange. I tried it on a completely different machine and had the same results. Bummer. It would be great to get this running, but ultimately, the project that I was looking to get running is where the assemblies are already packaged, which is with the Pdf-to-Image. solution. However, this one requires actual arguments, which are essential. All I am trying to do is set up a scenario where I can pass in a pdf, and create a single image file representing each page in the pdf. Whether one would run the executable as a CL process and pass in file / configuration options of some kind, or implement it inline in the code through a customized version of the Pdf-to-Image solution, there are currently no examples on how to do this either way (or any other way).

"Regarding examples they were built as a CLI examples, they take in command line arguments, if you run them from VS without specifying the command line args it will not work, you either need to open project settings and specify your args in the debug tab or build the proect and run exe as a standalone in your console."

Sure, I understand this, but that is exactly the problem: There are no actual examples, and without any, there is no way to truly know how the argument(s) should be structured and what other options there may be. Without this, as well as a way to compile the other solution, I am afraid this is heading towards a dead end. All of this looked promising, given there were quite a few different classes involved, additional libraries, etc. in these solutions, and the code looks clean, well-formed, and not a jumbled mess, yet with all this work, there are no actual working examples for Pdf-To-Image. It is equally odd as it is disappointing. Working directly with pdf's or graphics has not been my background, but this seems like a subject area where there should be many common, proven libraries to drop in to other solutions targeting specific business needs, but does not appear to be the case.

Separate from the build issues, the Pdf-to_Image project (as well as other projects in the different solutions) looks like a lot of promising, conceptual implementation work has been done, but without actual example method calls with properly-structured arguments that the libraries are expecting and in order for them to execute properly (which are critical for testing out different scenarios, getting familiar with how the methods in this tool works, customizing for specific usage, etc.), then it a nice looking concept that is just missing working examples to test out the functionality.

If you have any working examples of Pdf-to_Image that I could leverage as part of that solution (and just skip trying to work with the Docnet.Core solution), then that would be great. Then there would be something to work with, to test, debug, and leverage those findings to modify / integrate to my other solution for my specific needs.

[Modest-as]

Again not sure what you mean by working examples since this is one that works just fine and I can not replicate your issues on my machine nor other 10 machines I have tried on. I am closing this due to how vague this thread is. If you have good examples that you think community would contribute from please open a PR for them. I am sorry if the the examples that are there are not to your liking or detailed enough, contributions are always welcome.

[pauelm]

I am not talking about an example that is too my liking. I am talking about an example that can adequately demonstrate a working application. More specifically, I am talking about working examples that demonstrate the tool actually doing a conversion. I previously provided extensive details on this situation in order to help make this more clear. Forget about the issues with the main "Docnet" solution not compiling and building.

The only one that I am interested in leveraging on one of my projects is the "pdf-to-Image" solution.

If you focus just on the "pdf-to-Image" solution, and provide ONE actual example of the tool performing a conversion of a pdf converting each page to an image file, then it could properly demonstrate the tool working. Without that, and without demonstrating how the arguments are supposed to be structured and passed in to just the main function call, then there is not enough information to set up an actual test, demonstrate the tool performing a conversion of a pdf to image, which is the primary purpose of the pdf-to-image solution. When you execute the pdf-to-image solution, even the project complains about missing arguments. If there are not any examples demonstrating how to structure arguments into the main function call in Program.cs, then it is a project that compiles and builds but cannot execute. If someone were to ever have tested the pdf-to-image project to see how it works, or if it works at all, they would not be able to do that without at least a single working example to start with.

I cannot imaging someone writing all this code and never testing it, especially just the main function call. If they tested it, then whoever wrote the code for the pdf-to-image project would have some working examples that can demonstrate a conversion of a pdf pages to image files. If not, how could they have tested it, and how would they know the tool actually works? Basic details like this are vital to any project when testing and verifying an application code actually performs the function intended, as well as verifying proper output results. The same type of details are just as essential when going the opposite direction, when an engineer is reporting a defect to the developer that wrote the code. In that case, the engineer must provide specific example input criteria resulting in a defect, and how they executed the code in their repro steps, so that the developer can reproduce the defect, and then attempt to find root cause, debug, resolve, etc. Hopefully, this makes more sense now.