search

CreativeInquiry / PEmbroider

Embroidery Library for Processing
Other
443 stars 28 forks source link

Request for API reference #77

Closed golanlevin closed 3 years ago

golanlevin commented 4 years ago

OK, @LingDong- and @tatyanade : We will be launching PEmbroider sometime next week for our beta-testers. In preparation for this:

@LingDong- , I noticed r1b, the nice new renderer you built for thermal printers, and that you have a nice API reference: https://github.com/LingDong-/r1b/blob/master/API.md . Was this document automatically generated from source code comments? If so, could you please do the same for PEmbroider? I feel strongly that we need a cheat-sheet like this. Or was it assembled by hand?

@tatyanade I'd like to ask for your help in fleshing out the API reference so that it briefly explains all of the functions and how they should be used. Once @LingDong- tells us how we should proceed (automatically or by hand), I hope we can have a stab at this ready for our testers..

Hopefully, Golan

LingDong- commented 4 years ago

Hi @golanlevin ,

We already have an API Reference! It is generated by Javadoc from my source code comments, and can be viewed here: https://github.com/CreativeInquiry/PEmbroider/tree/master/distribution/PEmbroider/reference

It looks like this:

Screen Shot 2020-07-01 at 1 31 37 AM Screen Shot 2020-07-01 at 1 21 40 AM

Similarly, the API reference for r1b was generated with Doxygen (C/C++ counterpart of Javadoc), whose XML output I then parsed with a custom python script and re-generated to a Markdown version (because I thought the default HTML looks ugly and over-complicated). Maybe I can write something similar for Javadoc if you prefer Markdown format too. But I think the current Javadoc theme isn't too ugly, and maybe HTML captures better the complexity of this library (whereas r1b is a single header with flat structure which suits markdown better)

golanlevin commented 4 years ago

yeahhh..... The HTML not quite what I'm looking for. Unfortunately it's exhaustively "too complete" (too many functions, including functions we don't recommend or don't use anymore), so it's hard to get oriented; it's really best for looking up a specific term, not browsing. It also doesn't display within GitHub.com as interpreted HTML (unless I'm missing something).

I guess what I'm looking for is a "cheat sheet" ~2-3 pages long in total, which displays within the repository.

LingDong- commented 4 years ago

@golanlevin

Ah I see!

Well one way is that we use the "Github Pages" feature, but that doesn't solve the "too complete" problem.

I just checked and it seems like Javadoc doesn't support XML output. I'm thinking maybe let's use Doxygen, it supports Java too! So I can reuse my existing python script (https://github.com/LingDong-/r1b/blob/master/tools/make_md_doc.py in just 60 lines) for r1b to generate the Markdown cheatsheet.

The way I was dealing with internal functions in r1b was that my python script was searching for the words "(internal use)" in the source code comments and masking out these functions. So I think custom script is a good idea, we can potentially add even more customization to our output.

golanlevin commented 4 years ago

Very good, please make the changes. Let me and @tatyanade know where to modify the documentation/language, so that we can improve the explanations even more :)

LingDong- commented 4 years ago

@golanlevin @tatyanade

A draft edition of the API Reference is now available at:

https://github.com/CreativeInquiry/PEmbroider/blob/master/API.md

It is in markdown format, and has the same clean look & feel :)

Instructions

Building the docs

Doxygen is not related to eclipse, so the new docs can be re-built any time with simple instructions listed below:

cd tools # important to have correct working directory
python3 make_md_doc.py > ../API.md

If you're just testing things out, leave out the > ../API.md part, which will cause the output to be printed to the terminal instead.

Writing the docs

Currently most useful functions are already documented in the source code, though some of the advanced functions are also documented (hence generated too). To hide these in the cheatsheet, prefix the description with "(advanced use)" or "(internal use)" based on which is the case.

Some of the newer functions added in last week haven't been documented yet.

golanlevin commented 3 years ago

Hi @LingDong- I've made some more comments throughout the API -- could you kindly re-generate the documentation at https://github.com/CreativeInquiry/PEmbroider/blob/master/API.md ?

LingDong- commented 3 years ago

@golanlevin Sure, now updated: 5b2d5a6808f954dd6b493b1884c6fd95edab6190