Update public API docs

[chrissimpkins]

Adds the #![warn(missing_docs)] attribute and full public API documentation

Related #195

[cmyr]

Some comments inline that you are free to ignore :)

[cmyr]

Rust doc comments work a lot like git commits: the first line is used as a short summary (and is shown beside an item in the module level docs), and then anything after the first newline is "additional detail" and is only shown on the docs page for that specific item.

So basically: one short line that is a summary, and then anything else below the fold.

In this case though, I'm not sure that the new docs are an improvement on the previous ones? In particular I don't think it is necessary to mention that this returns &mut Self. This pattern should be familiar to the caller from std (see std::process::Command). If the previous docstring was too vague, I might instead say,

/// Specify whether layers (and glyphs) should be loaded.

[chrissimpkins]

Noted. I will have a look into this one tonight and respond.

[chrissimpkins]

Thanks for this information Colin. I agree with your comments here and revised the initial draft in fb78ef7

Please let me know if you feel that this improves the documentation in the section.

[chrissimpkins]

Related:

I've tended towards adding a # Notes header in documentation sections that have longer and/or multi-issue text content below the summary line. IMO this sets it off nicely in the HTML site, but this is very subjective. If you feel that this leads to unnecessary header clutter in the docs please let me know. I should have a full first draft available by the end of the day so that we can have a look.

[cmyr]

I think that std is a great guideline, and we should try to match the conventions used there. They don't seem to use # Note as a header very often, but they do often have lines that begin with 'Note:', for providing information that is not important in the general case, but is important to a deeper understanding of the API: see for instance the docs for String::drain.

I do think I've seen # Note: before, but generally for a longform exposition of some idea or concept, but I can't find an example. The best I can come up with is the A ghastly note section of PhantomData.

[chrissimpkins]

Tyvm! I'll do another pass through all of the new docs and remove unnecessary Note headers that do not follow this guideline.

Edit: 314e216 and 6c55831 address this issue

[chrissimpkins]

This is how it appears in the HTML

[chrissimpkins]

vs. this after 314e216

[chrissimpkins]

Some comments inline that you are free to ignore :)

Ty!!

[chrissimpkins]

font module doc updates in 1462bca

[chrissimpkins]

fontinfo module docs e038f7a

groups module docs 064d186

guideline module docs 4b59dbd

kerning module docs 1467c19

layer module docs d745027

shared_types module docs 5b6080d

write module docs 2c9325f

glyph module docs 01cc4e7

glyph::serialize docs 30a30a8

[chrissimpkins]

At this stage, I am simply trying to get a first draft of documentation in place across everything that is public. We're nearly there. There are 38 missing public X documentation warnings left as of 2c9325f, down from nearly 400.

The next step will be another pass for revisions with additional examples where appropriate and confirmation that the new content is valid/accurate, concise, and properly formatted in the production HTML site gen'd with cargo doc. Part of this effort will be to confirm that we use the proper rustdoc format as Colin noted in #197 (comment). I'll catch outstanding formatting issues that were not revised in the first draft on the next pass.

Please don't hesitate to edit this branch directly if you come across anything that should be changed.

[chrissimpkins]

As of 30a30a8, the entire public API is documented and clippy should no longer raise errors. Converted out of Draft status. This is ready for review. I will continue to work on the revisions noted in #197 (comment) and #197 (comment)

[chrissimpkins]

Rebased on #201

[madig]

Question about the breadth of the docs: In e.g. a Glyph, the name should not contain control characters and in the list of Unicode codepoints, the first one is the primary codepoint for the glyph (see https://unifiedfontobject.org/versions/ufo3/glyphs/glif/). Should this information be included in the norad docs?

[chrissimpkins]

IMO, yes. I am a fan of comprehensive docs.

[chrissimpkins]

Should we merge this before any significant source changes land? I can keep an eye out and rebase / edit in this branch if you'd prefer to keep this open for now.

[madig]

I'd like it merged so we have less work with subsequent PRs :) @cmyr ?

[cmyr]

Sure let's get this in and we can always touch it up later :)

[chrissimpkins]

Thank you both very much for the reviews!